diff options
Diffstat (limited to 'doc')
234 files changed, 38845 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 000000000..6812bd2d1 --- /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 000000000..171f575ce --- /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 Binary files differnew file mode 100644 index 000000000..0fdfe0cf0 --- /dev/null +++ b/doc/akregator/add-feed.png diff --git a/doc/akregator/add-feed2.png b/doc/akregator/add-feed2.png Binary files differnew file mode 100644 index 000000000..744da128d --- /dev/null +++ b/doc/akregator/add-feed2.png diff --git a/doc/akregator/add-folder.png b/doc/akregator/add-folder.png Binary files differnew file mode 100644 index 000000000..e49534814 --- /dev/null +++ b/doc/akregator/add-folder.png diff --git a/doc/akregator/add-folder2.png b/doc/akregator/add-folder2.png Binary files differnew file mode 100644 index 000000000..53590dd3a --- /dev/null +++ b/doc/akregator/add-folder2.png diff --git a/doc/akregator/advanced-tab.png b/doc/akregator/advanced-tab.png Binary files differnew file mode 100644 index 000000000..59dcac6c4 --- /dev/null +++ b/doc/akregator/advanced-tab.png diff --git a/doc/akregator/appearance-tab.png b/doc/akregator/appearance-tab.png Binary files differnew file mode 100644 index 000000000..3c3e29fa9 --- /dev/null +++ b/doc/akregator/appearance-tab.png diff --git a/doc/akregator/archive-tab.png b/doc/akregator/archive-tab.png Binary files differnew file mode 100644 index 000000000..41e52dad0 --- /dev/null +++ b/doc/akregator/archive-tab.png diff --git a/doc/akregator/browser-tab.png b/doc/akregator/browser-tab.png Binary files differnew file mode 100644 index 000000000..a02e93cc0 --- /dev/null +++ b/doc/akregator/browser-tab.png diff --git a/doc/akregator/general-tab.png b/doc/akregator/general-tab.png Binary files differnew file mode 100644 index 000000000..3cea71a78 --- /dev/null +++ b/doc/akregator/general-tab.png diff --git a/doc/akregator/index.docbook b/doc/akregator/index.docbook new file mode 100644 index 000000000..54b653de5 --- /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 "RSS +lozenge"<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 Binary files differnew file mode 100644 index 000000000..0dda199be --- /dev/null +++ b/doc/akregator/konq.png diff --git a/doc/akregator/konq2.png b/doc/akregator/konq2.png Binary files differnew file mode 100644 index 000000000..57c92b6dd --- /dev/null +++ b/doc/akregator/konq2.png diff --git a/doc/akregator/main-window.png b/doc/akregator/main-window.png Binary files differnew file mode 100644 index 000000000..4b0e59d33 --- /dev/null +++ b/doc/akregator/main-window.png diff --git a/doc/akregator/main-window2.png b/doc/akregator/main-window2.png Binary files differnew file mode 100644 index 000000000..308721914 --- /dev/null +++ b/doc/akregator/main-window2.png diff --git a/doc/akregator/main-window3.png b/doc/akregator/main-window3.png Binary files differnew file mode 100644 index 000000000..35b50c3fd --- /dev/null +++ b/doc/akregator/main-window3.png diff --git a/doc/akregator/main-window4.png b/doc/akregator/main-window4.png Binary files differnew file mode 100644 index 000000000..abff29c0e --- /dev/null +++ b/doc/akregator/main-window4.png diff --git a/doc/akregator/quick-filter.png b/doc/akregator/quick-filter.png Binary files differnew file mode 100644 index 000000000..c30d76783 --- /dev/null +++ b/doc/akregator/quick-filter.png diff --git a/doc/akregator/rss.png b/doc/akregator/rss.png Binary files differnew file mode 100644 index 000000000..3537e0f2b --- /dev/null +++ b/doc/akregator/rss.png diff --git a/doc/akregator/rss3.png b/doc/akregator/rss3.png Binary files differnew file mode 100644 index 000000000..3008a51da --- /dev/null +++ b/doc/akregator/rss3.png diff --git a/doc/api/Dox-pimlogo.png b/doc/api/Dox-pimlogo.png Binary files differnew file mode 100644 index 000000000..87934defc --- /dev/null +++ b/doc/api/Dox-pimlogo.png diff --git a/doc/api/Doxyfile.pim b/doc/api/Doxyfile.pim new file mode 100644 index 000000000..319ad1415 --- /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 000000000..e059f34a5 --- /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 000000000..cf3300b01 --- /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 Binary files differnew file mode 100644 index 000000000..8fbae210b --- /dev/null +++ b/doc/api/kdateedit.png diff --git a/doc/api/mainheader.html b/doc/api/mainheader.html new file mode 100644 index 000000000..3acce2c36 --- /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 000000000..171f575ce --- /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 Binary files differnew file mode 100644 index 000000000..cedbcec72 --- /dev/null +++ b/doc/kaddressbook/addhost.png diff --git a/doc/kaddressbook/conf.png b/doc/kaddressbook/conf.png Binary files differnew file mode 100644 index 000000000..2c4d7500f --- /dev/null +++ b/doc/kaddressbook/conf.png diff --git a/doc/kaddressbook/contactdlg.png b/doc/kaddressbook/contactdlg.png Binary files differnew file mode 100644 index 000000000..08d2d65e8 --- /dev/null +++ b/doc/kaddressbook/contactdlg.png diff --git a/doc/kaddressbook/edit_instant_messenging.png b/doc/kaddressbook/edit_instant_messenging.png Binary files differnew file mode 100644 index 000000000..84d1007a4 --- /dev/null +++ b/doc/kaddressbook/edit_instant_messenging.png diff --git a/doc/kaddressbook/exportdlg.png b/doc/kaddressbook/exportdlg.png Binary files differnew file mode 100644 index 000000000..6fc0f1abe --- /dev/null +++ b/doc/kaddressbook/exportdlg.png diff --git a/doc/kaddressbook/extension.png b/doc/kaddressbook/extension.png Binary files differnew file mode 100644 index 000000000..5c7bfd2f2 --- /dev/null +++ b/doc/kaddressbook/extension.png diff --git a/doc/kaddressbook/filtereditdlg.png b/doc/kaddressbook/filtereditdlg.png Binary files differnew file mode 100644 index 000000000..027363810 --- /dev/null +++ b/doc/kaddressbook/filtereditdlg.png diff --git a/doc/kaddressbook/index.docbook b/doc/kaddressbook/index.docbook new file mode 100644 index 000000000..9473fc520 --- /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 — +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 — 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><given name> <family name>;</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>FullName</guilabel></term> +<listitem><para><prefix> <given name> <additional name> +<family name> <suffix>;</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>ReverseName</guilabel></term> +<listitem><para><family name>, <given name>.</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 — 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><none></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 — +&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 — 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 — &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 — &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 <email></option></term> +<listitem><para>Shows the contact editor with the given email address.</para></listitem> +</varlistentry> +<varlistentry> +<term><command>kaddressbook</command> <option>--uid <uid></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 Binary files differnew file mode 100644 index 000000000..147ae19fc --- /dev/null +++ b/doc/kaddressbook/mainwin.png diff --git a/doc/kaddressbook/resourcedlg.png b/doc/kaddressbook/resourcedlg.png Binary files differnew file mode 100644 index 000000000..800552de0 --- /dev/null +++ b/doc/kaddressbook/resourcedlg.png diff --git a/doc/kaddressbook/resourcesdlg.png b/doc/kaddressbook/resourcesdlg.png Binary files differnew file mode 100644 index 000000000..7870fd1f1 --- /dev/null +++ b/doc/kaddressbook/resourcesdlg.png diff --git a/doc/kaddressbook/vieweditdlg.png b/doc/kaddressbook/vieweditdlg.png Binary files differnew file mode 100644 index 000000000..84ccd1d3b --- /dev/null +++ b/doc/kaddressbook/vieweditdlg.png diff --git a/doc/kalarm/Makefile.am b/doc/kalarm/Makefile.am new file mode 100644 index 000000000..171f575ce --- /dev/null +++ b/doc/kalarm/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/kalarm/alarmmessage.png b/doc/kalarm/alarmmessage.png Binary files differnew file mode 100644 index 000000000..da0fa1aeb --- /dev/null +++ b/doc/kalarm/alarmmessage.png diff --git a/doc/kalarm/editwindow.png b/doc/kalarm/editwindow.png Binary files differnew file mode 100644 index 000000000..cfb60992e --- /dev/null +++ b/doc/kalarm/editwindow.png diff --git a/doc/kalarm/index.docbook b/doc/kalarm/index.docbook new file mode 100644 index 000000000..28f44e788 --- /dev/null +++ b/doc/kalarm/index.docbook @@ -0,0 +1,4170 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&kalarm;"> + <!ENTITY package "kdepim"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"><!-- change language only here --> +]> + +<!-- The language must NOT be changed here. --> + +<book lang="&language;"> + +<bookinfo> +<title>The &kalarm; Handbook</title> + +<authorgroup> +<author> +<firstname>David</firstname> +<surname>Jarvie</surname> +<affiliation> +<address><email>&David.Jarvie.mail;</email></address> +</affiliation> +</author> + +<othercredit role="developer"> +<firstname>David</firstname> +<surname>Jarvie</surname> +<affiliation><address><email>&David.Jarvie.mail;</email></address></affiliation> +<contrib>Developer</contrib> +</othercredit> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2001</year><year>2002</year><year>2003</year><year>2004</year><year>2005</year><year>2006</year><year>2007</year><year>2008</year> +<holder>David Jarvie</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<!-- Don't change format of date and version of the documentation --> + +<date>2008-01-23</date> +<releaseinfo>1.05.00</releaseinfo> + +<abstract> +<para>&kalarm; is a personal alarm message, command and email scheduler for &kde;.</para> +</abstract> + + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdepim</keyword> +<keyword>kalarm</keyword> +<keyword>alarm</keyword> +<keyword>reminder</keyword> +</keywordset> + +</bookinfo> + + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&kalarm; lets you schedule the display of personal alarm +messages, the playing of sound files, the execution of commands and +the sending of emails.</para> + +<para>In its default graphical mode, &kalarm; displays the list of +pending alarms, showing their times and details. You can create new +alarms, or you can select existing alarms for modification or +deletion. You can also optionally view expired alarms.</para> + +<para>When configuring an alarm, you may either type in the alarm +message text, specify a text or image file to display, specify a +command to execute, or enter an email to send. You can also choose +the color of the alarm message, whether to play a sound or speak the +message, whether it should repeat, and whether the alarm should be +canceled if it cannot be triggered at its scheduled time.</para> + +<para>Alarms may also be scheduled from the command line, or via &DCOP; +calls from programs.</para> + +<para>When an alarm message is due, it is displayed on each &kde; +desktop to ensure that you don't miss it. The message window shows the +time for which the alarm was scheduled. It usually has a defer option +to ask for the alarm to be displayed again later. An example of an +alarm message:</para> + +<screenshot> +<screeninfo>Screenshot of the &kalarm; message window</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="alarmmessage.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Alarm message</phrase> +</textobject> +</mediaobject> +</screenshot> + +<para>When the alarm specifies a command to execute or an email to +send, &kalarm; displays nothing.</para> + +<para>&kalarm; can run in either of two modes: +<quote>continuous</quote> (the default) where it runs from the +system tray, or <quote>on-demand</quote> where it runs as and when +required (with the option of displaying an independent system tray +icon).</para> + +<para>This document makes various references to the <application>alarm +daemon</application>. This is an application which runs in the +background, checking pending alarms and telling &kalarm; to display +them when they become due.</para> + +</chapter> + +<chapter id="using-kalarm"> +<title>Using &kalarm;</title> + +<para>When it is run with no command line parameters, &kalarm; starts +in graphical mode, and displays the current list of outstanding +alarms.</para> + +<para>When &kalarm; starts in graphical mode, it checks whether the +<application>alarm daemon</application> is running. If it is not +already running, &kalarm; starts it.</para> + +<tip><para>All spin boxes in &kalarm; have an acceleration facility. +To make the value change by larger steps, hold down the +<keycap>Shift</keycap> key while you click on the spin arrow +buttons.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="spinbox.png" format="PNG"/> +</imageobject> +</mediaobject> +</tip> + +<sect1 id="alarm-list"> +<title>Alarm list</title> + +<para>The main &kalarm; window displays the current list of pending +alarms, showing their times, repetition intervals, colors, and +message texts, names of files to display, commands to execute or email +subjects. (For a recurring alarm, the time shown is its next scheduled +trigger time. For an alarm with a reminder, the time shown is the time +of the alarm proper, not the reminder time.) An icon at the left of +each alarm text/file/command/email subject indicates the type of +alarm.</para> + +<screenshot> +<screeninfo>Screenshot of the &kalarm; main window</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="mainwindow.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Main window</phrase> +</textobject> +</mediaobject> +</screenshot> + +<para>For a repeated alarm, the list shows its next scheduled trigger +time and its basic repetition interval (⪚ <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 – 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, ⪚ <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 & Color...</guibutton> button to +select a font, and foreground and background colors, for the alarm +message. In the <guilabel>Choose Alarm Font & 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 (⪚ 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 (⪚ 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 (⪚ <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 & 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 – assuming that the <application>alarm +daemon</application> is configured to start at login – 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, ⪚ +<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 & Color</title> + +<para>The <guilabel>Font & 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, ⪚ 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>), + ⪚ <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, ⪚ 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& <replaceable>calendarFile</replaceable>, + const QString& <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& <replaceable>calendarFile</replaceable>, + const QString& <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& <replaceable>calendarFile</replaceable>, + const QString& <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& <replaceable>message</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + const QString& <replaceable>bgColor</replaceable>, + const QString& <replaceable>fgColor</replaceable>, + const QString& <replaceable>font</replaceable>, + const KURL& <replaceable>audioURL</replaceable>, + int <replaceable>reminder</replaceable>, + const QString& <replaceable>recurrence</replaceable>, + int <replaceable>subRepeatInterval</replaceable>, + int <replaceable>subRepeatCount</replaceable>) +</synopsis> +<synopsis> +bool scheduleMessage(const QString& <replaceable>message</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, int <replaceable>flags</replaceable>, + const QString& <replaceable>bgColor</replaceable>, + const QString& <replaceable>fgColor</replaceable>, + const QString& <replaceable>font</replaceable>, + const KURL& <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& <replaceable>message</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + const QString& <replaceable>bgColor</replaceable>, + const QString& <replaceable>fgColor</replaceable>, + const QString& <replaceable>font</replaceable>, + const KURL& <replaceable>audioURL</replaceable>, + int <replaceable>reminder</replaceable>, + int <replaceable>recurType</replaceable>, + int <replaceable>recurInterval</replaceable>, + const QString& <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 (⪚ <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 – 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& <replaceable>URL</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + const QString& <replaceable>bgColor</replaceable>, + const KURL& <replaceable>audioURL</replaceable>, + int <replaceable>reminder</replaceable>, + const QString& <replaceable>recurrence</replaceable>, + int <replaceable>subRepeatInterval</replaceable>, + int <replaceable>subRepeatCount</replaceable>) +</synopsis> +<synopsis> +bool scheduleFile(const KURL& <replaceable>URL</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + const QString& <replaceable>bgColor</replaceable>, + const KURL& <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& <replaceable>URL</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + const QString& <replaceable>bgColor</replaceable>, + const KURL& <replaceable>audioURL</replaceable>, + int <replaceable>reminder</replaceable>, + int <replaceable>recurType</replaceable>, + int <replaceable>recurInterval</replaceable>, + const QString& <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 (⪚ <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& <replaceable>commandLine</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + const QString& <replaceable>recurrence</replaceable>, + int <replaceable>subRepeatInterval</replaceable>, + int <replaceable>subRepeatCount</replaceable>) +</synopsis> +<synopsis> +bool scheduleCommand(const QString& <replaceable>commandLine</replaceable>, + const QString& <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& <replaceable>commandLine</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + int <replaceable>recurType</replaceable>, + int <replaceable>recurInterval</replaceable>, + const QString& <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& <replaceable>fromID</replaceable>, + const QString& <replaceable>addresses</replaceable>, + const QString& <replaceable>subject</replaceable>, + const QString& <replaceable>message</replaceable>, + const QString& <replaceable>attachments</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + int <replaceable>flags</replaceable>, + const QString& <replaceable>recurrence</replaceable>, + int <replaceable>subRepeatInterval</replaceable>, + int <replaceable>subRepeatCount</replaceable>) +</synopsis> +<synopsis> +bool scheduleEmail(const QString& <replaceable>fromID</replaceable>, + const QString& <replaceable>addresses</replaceable>, + const QString& <replaceable>subject</replaceable>, + const QString& <replaceable>message</replaceable>, + const QString& <replaceable>attachments</replaceable>, + const QString& <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& <replaceable>fromID</replaceable>, + const QString& <replaceable>addresses</replaceable>, + const QString& <replaceable>subject</replaceable>, + const QString& <replaceable>message</replaceable>, + const QString& <replaceable>attachments</replaceable>, + const QString& <replaceable>dateTime</replaceable>, + int <replaceable>lateCancel</replaceable>, + nt <replaceable>flags</replaceable>, + int <replaceable>recurType</replaceable>, + int <replaceable>recurInterval</replaceable>, + const QString& <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& <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& <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 Binary files differnew file mode 100644 index 000000000..a1c58908d --- /dev/null +++ b/doc/kalarm/mainwindow.png diff --git a/doc/kalarm/spinbox.png b/doc/kalarm/spinbox.png Binary files differnew file mode 100644 index 000000000..ef9db8972 --- /dev/null +++ b/doc/kalarm/spinbox.png diff --git a/doc/kandy/Makefile.am b/doc/kandy/Makefile.am new file mode 100644 index 000000000..171f575ce --- /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 000000000..c1a952a33 --- /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 000000000..085981d9b --- /dev/null +++ b/doc/karm/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/karm/clipboard-history.png b/doc/karm/clipboard-history.png Binary files differnew file mode 100644 index 000000000..ee0b04d32 --- /dev/null +++ b/doc/karm/clipboard-history.png diff --git a/doc/karm/copy-this-task.png b/doc/karm/copy-this-task.png Binary files differnew file mode 100644 index 000000000..f5c89bea2 --- /dev/null +++ b/doc/karm/copy-this-task.png diff --git a/doc/karm/csvexport.png b/doc/karm/csvexport.png Binary files differnew file mode 100644 index 000000000..7dc5f8e54 --- /dev/null +++ b/doc/karm/csvexport.png diff --git a/doc/karm/daterange.png b/doc/karm/daterange.png Binary files differnew file mode 100644 index 000000000..3ad3a70f7 --- /dev/null +++ b/doc/karm/daterange.png diff --git a/doc/karm/idle-detect.png b/doc/karm/idle-detect.png Binary files differnew file mode 100644 index 000000000..43bf71811 --- /dev/null +++ b/doc/karm/idle-detect.png diff --git a/doc/karm/index.docbook b/doc/karm/index.docbook new file mode 100644 index 000000000..be0faf1ee --- /dev/null +++ b/doc/karm/index.docbook @@ -0,0 +1,1238 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&karm;"> + <!ENTITY package "kdepim"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> + <!ENTITY % addindex "IGNORE"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &karm; Handbook</title> + +<authorgroup> +<author> +<firstname>Jonathan</firstname> +<surname>Singer</surname> +<affiliation> +<address><email>jsinger@leeta.net</email></address> +</affiliation> +</author> + +<author> +<firstname>Mark</firstname> +<surname>Bucciarelli</surname> +<affiliation> +<address><email>mark@hubcapconsulting.com</email></address> +</affiliation> +</author> + +<author> +<firstname>Sirtaj</firstname> +<othername>Singh</othername> +<surname>Kang</surname> +<affiliation><address><email>taj@kde.org</email></address></affiliation> +</author> + +<othercredit role="reviewer"> +<firstname>Lauri</firstname> +<surname>Watts</surname> +<contrib>Reviewer</contrib> +<affiliation><address><email>lauri@kde.org</email></address></affiliation> +</othercredit> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2000-2004</year> +<holder>Jonathan Singer</holder> +</copyright> + +<copyright> +<year>2004-2005</year> +<holder>Mark Bucciarelli</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2005-02-02</date> +<releaseinfo>1.5.0</releaseinfo> + +<abstract><para>&karm; tracks time spent on various tasks.</para></abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>karm</keyword> +<keyword>kdeutils</keyword> +<keyword>time</keyword> +<keyword>tracker</keyword> +<keyword>project</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&karm; tracks time spent on various tasks. It is useful for tracking + billable hours and can report the hours logged by task and day.</para> + +<para>This time history can be exported to a comma-delimited text file for + import into other billing and/or project management tools.</para> + +<para>&karm; detects when your keyboard and mouse are idle and can associate + different tasks with different desktops, two tools that can help keep the + timer running on the correct task.</para> + +<para>&karm; was originally written by Sirtaj Singh Kang. The word +<quote>karm</quote> means <quote>work</quote> or <quote>deeds</quote> in the +author's native Punjabi and is the same word (but a better transliteration) +as <quote>karma</quote>.</para> + +</chapter> + + +<chapter id="using-Karm"> +<title>Using &karm;</title> + +<sect1 id="starting"> +<title>Starting &karm;</title> + +<para>Type <command>karm</command> at a command prompt or select +<guimenuitem>Personal Time Tracker</guimenuitem> from the +<guisubmenu>Utilities</guisubmenu> group in the <guimenu>KDE start +menu</guimenu>. The standard &Qt; and &kde; command options are +available, and can be listed by entering +<userinput><command>karm</command> <option>--help</option></userinput> +at the command line.</para> + +<para>&karm; provides an additional command option that allows you to enter +the name of the iCalendar file that is used to store your labor history. +You enter a remote iCalendar file by using http or ftp as part of the file +name; for example, http://www.mysite.com/mydata/mylabor.ics.</para> + +</sect1> + +<sect1 id="general-use"> +<title>Tasks</title> + +<informalexample> +<para><emphasis>Problem:</emphasis> You are a free software consultant with +many clients. Some clients have multiple projects. During the course of a +day, you switch back and forth between different projects. You need to track +your time to generate monthly invoices.</para> +<para><emphasis>Solution:</emphasis> Create one top-level task for each client +and a subtask for each client project. For projects that require more +detailed tracking, create a list of project subtasks. Track time by +double-clicking on task you are currently working on.</para> +</informalexample> + +<para>&karm; provides great flexibility in tracking your time, allowing +unlimited tasks and task depth. Time may be logged to any task, and more than +one task can be active at any given time.</para> + +<para> +To create a top-level task, select +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo> +</shortcut> +<guimenu>Task</guimenu> +<guimenuitem>New</guimenuitem> +</menuchoice> + +To create a subtask, pick the parent task and select + +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Alt;<keycap>N</keycap></keycombo> +</shortcut> +<guimenu>Task</guimenu> +<guimenuitem>New Subtask</guimenuitem> +</menuchoice> +</para> + +<para>When &karm; exits, the task list is saved to the file specified in +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure KArm</guimenuitem> +</menuchoice>. +When it next opens, it reloads the task list from the same file.</para> + +<para>&karm; can import and export tasks to minimize your work. See <link linkend="interfaces">Other Systems</link>.</para> + +</sect1> + +<sect1 id="timers"><title>Timers</title> + +<informalexample> +<para><emphasis>Problem:</emphasis> To remain solvent, you must bill an +average of five hours a day. To stay on track, you watch your daily and +weekly totals.</para> +<para><emphasis>Solution:</emphasis> Reset the session timer at the +beginning of each work day and reset all timers at the beginning of each +week.</para> </informalexample> + +<para>&karm; makes tracking time simple. To start logging time against a +task, double-click on the task. To stop logging time, double-click +the task again. Active tasks display a small clock in the <guilabel>Session +Time</guilabel> column.</para> + +<para>Another visual clue of logging activity is the &karm; system tray icon. +When a task is active, the second hand in the icon moves. If you rest the +mouse pointer over this icon, the name of the active task will display in a +tooltip. If more than one task is active, the task names in the tooltip are +separated by commas.</para> + +<para>&karm; maintains two timers for each task: one for the session time +and one for the total time. In the default configuration, &karm; displays +two columns for each timer, resulting in a total of four columns for each task:</para> + +<variablelist> +<varlistentry> <term><guilabel>Session Time</guilabel></term> +<listitem><para>The time spent on the task since the session +began.</para></listitem> </varlistentry> + +<varlistentry> <term><guilabel>Total Session Time</guilabel></term> +<listitem><para>The time spent on the task and all it's subtasks since the +session began.</para></listitem> </varlistentry> +<varlistentry> <term><guilabel>Time</guilabel></term> <listitem><para>The time +spent on the task since all times were reset.</para></listitem> +</varlistentry> + +<varlistentry> <term><guilabel>Total Time</guilabel></term> +<listitem><para>The time spent on the task and all it's subtasks since all +times were reset.</para></listitem> </varlistentry> +</variablelist> + +<para>To start a new session, select +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Start New Session</guimenuitem> +</menuchoice> +</para> + +<para>To reset all times, select +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Reset All Times</guimenuitem> +</menuchoice> +</para> + +<sect2><title>Desktop Tracking</title> + +<informalexample> +<para><emphasis>Problem:</emphasis> You have two main projects that you +switch between each day. To help organize your work, you keep your project +1 files on Desktop 1 and your project 2 files on Desktop +2.</para> + +<para><emphasis>Solution:</emphasis> Associate project 1 task with Desktop 1 +and the project 2 task with Desktop 2. When you switch from Desktop 2 to +Desktop 1 active, &karm; automatically stops the project 2 task and starts +the project 1 task.</para> +</informalexample> + +<para>To associate a task with a one or more desktops, select +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo> +</shortcut> +<guimenu>Task</guimenu> +<guimenuitem>Edit</guimenuitem> +</menuchoice>. + +Turn on <guilabel>Auto tracking</guilabel> and select the desktop or desktops +to associate with this task. When any of the selected desktops becomes active, +after a short delay &karm; will be automatically start logging time against +that task.</para> + +</sect2> + +<sect2><title>Idle Detection</title> + +<informalexample> <para><emphasis>Problem:</emphasis> You leave work early on +Friday to run an errand and forget to stop the timer. When you return on +Monday, the timer is still running.</para> +<para><emphasis>Solution:</emphasis> Turn on idle detection.</para> +</informalexample> + +<para>&karm; can be configured to detect when the mouse and keyboard become + idle. If the mouse and keyboard are idle for longer than the specified + number of minutes, &karm; displays the following dialog:</para> + +<screenshot> + <screeninfo>&karm; Idle Detection</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="idle-detect.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>&karm; Idle Detection Dialog</phrase> + </textobject> + </mediaobject> +</screenshot> + +<variablelist> +<varlistentry><term><guibutton>Revert & 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 & 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älvdalens Datakonsult AB</para></listitem> +<listitem><para>Mark Bucciarelli <email>mark@hubcapconsulting.com</email></para></listitem> +<listitem><para>Thorsten Stä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 Binary files differnew file mode 100644 index 000000000..0c4a0a3cc --- /dev/null +++ b/doc/karm/karm.png diff --git a/doc/karm/systray.png b/doc/karm/systray.png Binary files differnew file mode 100644 index 000000000..2b5459d2f --- /dev/null +++ b/doc/karm/systray.png diff --git a/doc/kleopatra/Makefile.am b/doc/kleopatra/Makefile.am new file mode 100644 index 000000000..085981d9b --- /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 000000000..ba4672156 --- /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/">Ägypten +Projects</ulink> (Ä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, ⪚ 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; (⪚ 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 (⪚ 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 (⪚ 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—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; (⪚ 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> ⪚ 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 (⪚ 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 ⪚ 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 (⪚ <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 (⪚ 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> = <literal>is</literal>), + has anything but + (<replaceable>prefix</replaceable> = <literal>is-not</literal>), + has at least + (<replaceable>prefix</replaceable> = <literal>is-at-least</literal>), + or has at most + (<replaceable>prefix</replaceable> = <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älvdalens Datakonsult AB</para> + +<para>Documentation copyright 2002 &Steffen.Hansen;, copyright 2004 +&Daniel.Molkentin;, copyright 2004 Klarä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 000000000..085981d9b --- /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 000000000..a66665ad3 --- /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ä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 & 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 +<joe@example.com></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, ⪚ 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, ⪚ 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 & 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 (⪚ the <quote>> + </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 ⪚ + <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 %-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> + (⪚ 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, ⪚ 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 "Don't Ask Again" 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 >= 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 (⪚ <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 000000000..ec986f5cf --- /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ö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ä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ü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): Ä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): Ä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ö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ö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 000000000..f7ef1e682 --- /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, ⪚ +<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 ⪚ <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&m=99220697415300&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, ⪚ 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 — 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 (⪚ 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 000000000..c70249e7c --- /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 (⪚ <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 (⪚ <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 +(⪚ <userinput>My Mail Account</userinput>) +and the <guilabel>Host</guilabel> +field with the name and domain of your mail server +(⪚ <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 "Check Mail"</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 +<guilabel>Destination folder</guilabel>. But what you probably want is a +<link linkend="filters">filter</link>, which has nothing to do with this +option.</para> + +<para>With <guilabel>Precommand</guilabel> you can specify any program that &kmail; +will execute just before fetching mail. Please specify the full path +(do not use <quote>~</quote>) and note that &kmail; will not continue +until the program returns.</para> + +<para>On the <guilabel>Extras</guilabel> tab you can select <guilabel>Use +pipelining for faster mail download</guilabel> if this is supported by your +server. You should carefully test this to make sure it works safely.</para> +</sect3> + +<sect3 id="receiving-mail-imap-pop3"> +<title>Options for both <acronym>IMAP</acronym> and POP3</title> + +<!-- TODO: move all this, this isn't important for beginners?! --> +<para>If you select <guilabel>Store POP password in configuration +file</guilabel> or <guilabel>Store IMAP password in configuration +file</guilabel> &kmail; will remember your password so you will not have to +type it every time you start &kmail; and fetch new mail.</para> + +<warning><para>Be warned that &kmail; cannot really encrypt your password, so +people who can access your configuration files (⪚ system +administrators) can easily get your password if you select this +option.</para></warning> + +<para>&kmail; supports encryption via <guilabel>SSL</guilabel> and +<guilabel>TLS</guilabel> (<guilabel>TLS</guilabel> should be preferred +if it is available).</para> + +<para>For POP3 &kmail; supports:</para> + +<itemizedlist> +<listitem><para><guilabel>Clear text</guilabel>, </para></listitem> +<listitem><para><guilabel>PLAIN</guilabel>, </para></listitem> +<listitem><para><guilabel>LOGIN</guilabel>, </para></listitem> +<listitem><para><guilabel>CRAM-MD5</guilabel> (recommended +if <guilabel>DIGEST-MD5</guilabel> is not available),</para></listitem> +<listitem><para><guilabel>DIGEST-MD5</guilabel> (recommended) and</para></listitem> +<listitem><para><guilabel>APOP</guilabel> authentication.</para></listitem> +</itemizedlist> + +<para><guilabel>DIGEST-MD5</guilabel>, <guilabel>CRAM-MD5</guilabel> and +<guilabel>APOP</guilabel> are secure on their own, the other +options are only secure when used together with <guilabel>SSL</guilabel> +or <guilabel>TLS</guilabel>. You should only use <guilabel>Clear +text</guilabel> if your server does not support any of the other +authentication methods. Additionally, for <acronym>IMAP</acronym> +<guilabel>Anonymous</guilabel> is supported, but <guilabel>APOP</guilabel> +is not. Use the <guibutton>Check what the server supports</guibutton> button +on the <guilabel>Extras</guilabel> or <guilabel>Security</guilabel> tab +to automatically select the most secure settings supported by your server.</para> + +<para>You are now ready to send and receive mail. For +<acronym>IMAP</acronym>, just open your folders in the +folder tree in &kmail;'s main window. &kmail; then connects to your +server and displays the messages it finds. For POP3 use +<menuchoice><guimenu>File</guimenu><guimenuitem>Check +Mail</guimenuitem></menuchoice>.</para> + +</sect3> + +</sect2> + +</sect1> + +<sect1 id="testing-your-setup"> +<title>Testing your Setup</title> + +<para>First, you should send yourself a message to test your +configuration. To send a message, either hit <keycombo +action="simul">&Ctrl;<keycap>N</keycap></keycombo>, select the +<guiicon>New Message</guiicon> icon or select +the <menuchoice><guimenu>Message</guimenu><guimenuitem>New +Message...</guimenuitem></menuchoice> menu item. The +<link linkend="the-composer-window">composer window</link> will appear. Fill in the +<guilabel>To:</guilabel> field with your email address and type +something in the <guilabel>Subject</guilabel> field. Send the message by +selecting <menuchoice><guimenu>Message</guimenu> <guimenuitem>Send</guimenuitem> +</menuchoice>.</para> + +<para>To check your email, select +<menuchoice><guimenu>File</guimenu><guimenuitem>Check +Mail</guimenuitem></menuchoice>. In the lower right corner of the main +window, a progress bar will indicate how many messages are being +downloaded. If you receive the message you just sent, then +congratulations! If, however, you receive any error messages while +testing your setup, make sure that your network connection is working +and recheck your settings at +<menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure +&kmail;...</guimenuitem></menuchoice>.</para> + +</sect1> + +</chapter> diff --git a/doc/kmail/importing.docbook b/doc/kmail/importing.docbook new file mode 100644 index 000000000..6cc909631 --- /dev/null +++ b/doc/kmail/importing.docbook @@ -0,0 +1,270 @@ +<chapter id="importing"> + +<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>2002-10-03</date> +<releaseinfo>1.5</releaseinfo> +</chapterinfo> + +<title>Using other Mailbox Files with &kmail;</title> + +<para>&kmail; offers an import tool for the messages and address books of some +other email clients. You can access it using <menuchoice><guimenu>Tools</guimenu> +<guimenuitem>Import...</guimenuitem></menuchoice>. Please make sure that you +compact your folders in the other email client, no matter if you are going to use +the import utility or if you are going to copy files manually. +You only need to read this chapter if this tool does not work for you.</para> + +<para>This section is for all of the users who need to move email messages +from their previous email client over to &kmail;. &kmail; can store its +messages using <quote>mbox</quote> or <quote>maildir</quote> formats, which +are the most widely-used mailbox formats on &UNIX; systems. Mbox mailboxes +store messages in one file, identifying where messages start and end with a +<literal>From</literal> line (do not mix this up with the +<literal>From:</literal> header that contains the message's sender); +Maildir uses one file per message. For many &UNIX; email clients, all you +must do is move your mailboxes to <filename +class="directory">~/Mail</filename> (or make <filename +class="symlink">Mail</filename> a symbolic link to the folder containing +your mailboxes), make sure they are writable by your user, and launch +&kmail;. The mailboxes should now show up correctly in &kmail;.</para> + +<para>Please have a look at the +<ulink url="http://kmail.kde.org/tools.html">Tools section of &kmail;'s +homepage</ulink> first, to see if there is a tool that imports your mailbox +and maybe even address book.</para> + +<warning><para>Do not use a second email client that accesses the files in +<filename class="directory">~/Mail</filename> while &kmail; is running or +you might lose messages. This section only explains how to import mailboxes +to &kmail; once; it is not useful to you if you're planning to use several +email clients for your mailboxes in the future.</para></warning> + +<variablelist> + +<varlistentry> +<term><application>Eudora Lite</application>/<application>Eudora +Pro</application></term> +<listitem> +<para><application>Eudora</application> uses the mbox format in its mail +files. To use them with &kmail;, make sure that your +<application>Eudora</application> mailboxes have been compacted, then copy the +<literal role="extension">.mbx</literal> files (&Windows; +<application>Eudora</application>) or <application>Eudora</application> mailbox +files (&Mac; <application>Eudora</application>) to your <filename +class="directory">~/Mail</filename> folder. You do not need to copy the +<filename>index</filename> files. Once you start &kmail;, the mailboxes should +appear in the Folders pane and the messages should be accessible in the Headers +pane.</para> +<para>If messages do not appear in the Headers pane, your mailbox files may +still contain &Windows; or &Mac; line-feed characters. Use your favorite +text editor, the <application>recode</application> command or a scripting +language to change the &Windows; or &Mac; line feeds to &UNIX; line +feeds.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><application>Mailsmith</application></term> +<listitem> +<para><application>Mailsmith</application> runs on &Mac; and uses its own database +format; however it is possible to export mail into mbox format using +<menuchoice><guimenu>File</guimenu><guimenuitem>Export +Mail</guimenuitem></menuchoice> on a +selected mailbox or on selected messages. Once the messages have been exported, translate +the &Mac; line breaks to &UNIX; line breaks using your favorite editor, or using the following +command under &Linux;:</para> + +<para><userinput><command>cat</command> <option>mail-mac.txt</option> +| perl -e 'while (<STDIN>) { s/\r/\n/gi; print $_ ;}' > mail-unix.txt</userinput></para> + +<para>&kmail; will only recognize mboxes placed directly in the <filename class="directory">~/Mail/</filename> +folder. This means that a folder hierarchy cannot be preserved by simply moving files into the +<filename class="directory">~/Mail/</filename> folder, but will need to be reconstructed +within &kmail; manually.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term>MMDF</term> +<listitem> +<para>This format is close enough to the mailbox format that &kmail; should be +able to use these mailboxes if you just copy them to your +<filename class="directory">~/Mail</filename> folder; however, MMDF mailboxes +have not been tested with &kmail;, so your results may vary. If you can get +this format to work with &kmail;, please let us know so we can include more +specific directions in the next documentation release.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>MH mailboxes</term> +<listitem> +<para>MH mailboxes are directories containing files that correspond to each +message in that mailbox. A shell script to convert MH mailboxes to mbox +mailboxes, <command>mh2kmail</command>, is included at least in the source +releases of &kmail;, but maybe not in the packaged releases. Running this script +on a MH folder will convert it to an mbox file. We strongly suggest that you +back up your MH mail folders before you use this script.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Forte <application>Agent</application></term> +<listitem> +<para>In <application>Agent</application>:</para> +<procedure> +<step> +<para>Select the messages to export</para> +</step> +<step> +<para>Select <menuchoice><guimenu>FILE</guimenu><guimenuitem>SAVE MESSAGES +AS</guimenuitem></menuchoice></para> +</step> +<step> +<para>Mark the <guilabel>UNIX FORMAT</guilabel> and <guilabel>SAVE +RAW</guilabel> boxes</para> +</step> +<step> +<para>Give File a <literal role="extension">.txt</literal> extension and +save.</para> +</step> +</procedure> + +<para>In &kde;:</para> + +<procedure> +<step> +<para>Move the previously-saved file to the correct <filename +class="directory">~/Mail</filename> folder</para> +</step> +<step> +<para>Rename file without <literal role="extension">.txt</literal> +extension</para> +</step> +</procedure> +<para>When you open &kmail; the new folder with appropriate messages will be +there.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>&Netscape; Mail</term> +<listitem> + +<para>If you are using &Netscape; 4.x, the mail files should be found +in <filename class="directory">~/nsmail</filename>; if you are using +&Netscape; 6.x, they're buried in a folder deep in the <filename +class="directory">~/.mozilla</filename> subfolder, something like: +<filename +class="directory">/home/user_name/.mozilla/user_name/2ts1ixha.slt/Mail/Mail/server_name</filename> +(the <filename class="directory">2ts1ixha.slt</filename> string will +probably vary, so check it on your own system.) The <filename +class="directory">[...]/Mail/Mail</filename> folder contains one +subfolder for each account from which you receive mail through +Netscape (⪚ <filename +class="directory">[...]/Mail/Mail/math.university.edu</filename>); +you will need to copy files from each of them if you want everything to +be accessible under &kmail;.</para> + +<para>If you have no subfolders, just copy all of the &Netscape; +files to <filename class="directory">~/Mail</filename>, make sure +that they are writable (only by your user, of course), and restart +&kmail;: all of the messages will now appear in &kmail; folders. +(Note that if you use a command like <command>cp +<parameter>*</parameter> <parameter>~/Mail</parameter></command>, you +should follow it with <command>rm <option>-f</option> +<parameter>~/Mail/*.msf</parameter></command>; every &Netscape; 6 +folder has a corresponding <filename>.msf</filename> file, and if you +do not get rid of them you will have a bunch of spurious empty +folders.)</para> + +<para>If you were using subfolders under &Netscape; (⪚ a main +folder called <replaceable>Work</replaceable> with subfolders called +<replaceable>Jim</replaceable> and <replaceable>Nancy</replaceable>), +there are additional steps required. First, create the main folder +(<replaceable>Work</replaceable>) in &kmail; and create a temporary +child folder under it (by right-clicking on the folder name and +selecting <guilabel>Create child folder</guilabel>); it does not +matter what you call this folder -- <replaceable>dummy</replaceable> +or the default <replaceable>unnamed</replaceable>, for example. Once +a child folder has been requested, &kmail; creates a hidden folder +in <filename class="directory">~/Mail</filename> called (in this +example) <filename class="directory">.Work.directory</filename>. You +can then copy your &Netscape; subfolder files +(<replaceable>Jim</replaceable> and <replaceable>Nancy</replaceable>) +into <filename class="directory">~/Mail/.Work.directory</filename>, +and restart &kmail;; the child folders will appear under the main +folder <replaceable>Work</replaceable>. Of course, this procedure may +be extended for sub-subfolders, to any depth. (You can remove the +temporary child folders afterwards, unless it amuses you to have a +<replaceable>Work</replaceable> subfolder called +<replaceable>dummy</replaceable>.)</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><application>Pegasus Mail</application></term> +<listitem> +<para><application>Pegasus</application> for win32 uses single files for Mail +folders similar to &kmail;. <application>Pegasus mail</application> folder files +have the extension <literal role="extension">.pmm</literal> but they are the same format as mbox except the messages +do not start with the <literal>From</literal> header, but with a control character. To work around +this, replace each instance of the control character with <literal>From +aaa@aaa Mon Jan 01 00:00:00 1997</literal>. This <literal>From</literal> +line should be the first line of every message, before the +<literal>Received:</literal> and other headers. Make sure to use a text editor +that lets you save the files in &UNIX; format or create new folders in +<application>Pegasus</application> that are in &UNIX; format and copy your messages +there.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Maildir / Outlook Express / xfmail</term> +<listitem> +<para>Tools to convert these formats are available at the +<ulink url="http://kmail.kde.org/tools.html">Tools section of &kmail;'s +homepage</ulink>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Lotus <application>Notes</application>, BeOS Mail files, <application>cc: +Mail</application>, &etc;...</term> +<listitem> +<para>First you should have a look at <ulink +url="http://kmail.kde.org/tools.html">Tools section of &kmail;'s homepage</ulink> if +there are tools to convert your messages.</para> +<para>Mail programs not listed here or on the homepage probably do not work with &kmail; as they use +proprietary mail formats that &kmail; cannot understand. However, there is no +harm in trying! If the mailbox file looks similar to the mbox format, try +copying the mailbox file (remember, the index file is not needed) to your +<filename class="directory">~/Mail</filename> folder and see what happens if you start +&kmail;. If you get mailboxes from your favorite email client to work in &kmail;, +please tell us how you did it so that we can include directions in a future +revision of this documentation. </para> +</listitem> +</varlistentry> + +</variablelist> + +</chapter> diff --git a/doc/kmail/index.docbook b/doc/kmail/index.docbook new file mode 100644 index 000000000..fe38a5100 --- /dev/null +++ b/doc/kmail/index.docbook @@ -0,0 +1,161 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&kmail;"> + <!ENTITY package "kdepim"> + <!ENTITY kmail-intro SYSTEM "intro.docbook"> + <!ENTITY kmail-getting-started SYSTEM "getting-started.docbook"> + <!ENTITY kmail-using-kmail SYSTEM "using-kmail.docbook"> + <!ENTITY kmail-configure SYSTEM "configure.docbook"> + <!ENTITY kmail-menus SYSTEM "menus.docbook"> + <!ENTITY kmail-faq SYSTEM "faq.docbook"> + <!ENTITY kmail-importing SYSTEM "importing.docbook"> + <!ENTITY kmail-credits-and-licenses SYSTEM "credits-and-licenses.docbook"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> + <!ENTITY html "<acronym>HTML</acronym>"> + <!ENTITY gpg "<application>GPG</application>"> + <!ENTITY gpgsm "<application>GpgSM</application>"> + <!ENTITY mdn "<acronym>MDN</acronym>"> + <!ENTITY acl "<acronym>ACL</acronym>"> + <!ENTITY imap "<acronym>IMAP</acronym>"> + <!ENTITY nntp "<acronym>NNTP</acronym>"> + <!ENTITY openpgp "<acronym>OpenPGP</acronym>"> + <!ENTITY smime "<acronym>S/MIME</acronym>"> + <!ENTITY kolab "<acronym>Kolab</acronym>"> +]> +<book lang="&language;"> +<bookinfo> +<title>The &kmail; Handbook</title> + + <!-- Note: +* please do not mix up the formatting more than necessary so that + "cvs diff" makes useful output +* no short forms +* use <warning> instead of <caution> +--> + +<!-- TODO: +*index (see kdegames/kpat/) + +* guisubmenu vs. guititem ?? +* more about security? + +* Configure KMail: "page" or "tab", but no mix of both! +* add section for drag'n'drop? +* "Using other mailbox..." -> sounds strange? + +* use better markup instead of 'quote'? +* fix my adverb vs. adjective mistakes + +* coherent wording for section / tab / ... +* <menuchoice><guimenu>xxx , or is <guimenu>xxx enough? +* <guiicon> vs. <guibutton> +* spelling: popup vs pop up, frontend vs front end + +* message vs. mail vs. email -> using "message" everywhere +* window vs. dialog: a dialog is modal, a window is not (I think) + +* in KMail: kmail vs. KMail +--> + +<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> + +<copyright> +<year>1999</year> +<year>2000</year> +<year>2001</year> +<year>2002</year> +<holder>David Rugge</holder> +</copyright> +<copyright> +<year>2003</year> +<holder>Daniel Naber</holder> +</copyright> +<copyright> +<year>2004</year> +<holder>Daniel Naber</holder> +<holder>Ingo Klöcker</holder> +</copyright> + +<abstract> + +<para>&kmail; is &kde;'s powerful and user friendly email client.</para> + +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>Mail</keyword> +<keyword>email</keyword> +<keyword>Client</keyword> +<keyword>POP3</keyword> +<keyword>IMAP</keyword> +<keyword>PGP</keyword> +<keyword>GnuPG</keyword> +<keyword>GPG</keyword> +<keyword>Kolab</keyword> +</keywordset> +</bookinfo> + +&kmail-intro; +&kmail-getting-started; +&kmail-using-kmail; +&kmail-configure; +&kmail-menus; +&kmail-faq; +&kmail-importing; +&kmail-credits-and-licenses; + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-kmail"> +<title>How to obtain &kmail;</title> + +&install.intro.documentation; + +</sect1> + +<sect1 id="compilation"> +<title>Compilation and Installation</title> + +&install.compile.documentation; + +</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=0:sw=2:tw=78:noet +--> diff --git a/doc/kmail/intro.docbook b/doc/kmail/intro.docbook new file mode 100644 index 000000000..29d7173af --- /dev/null +++ b/doc/kmail/intro.docbook @@ -0,0 +1,56 @@ +<chapter id="intro"> + +<chapterinfo> +<authorgroup> +<author> +<firstname>Daniel</firstname> +<surname>Naber</surname> +<affiliation><address> +<email>daniel.naber@t-online.de</email> +</address></affiliation> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +<date>2004-07-13</date> +<releaseinfo>1.7</releaseinfo> +</chapterinfo> + +<title>Introduction</title> + +<para>The &kmail; Team welcomes you to &kmail;, a user-friendly email client for the +K Desktop Environment. Our goal is to make &kmail; a program that is beautiful +and intuitive without sacrificing power. </para> + +<para>If you have never set up an email client on a &UNIX; system +before, we suggest that you read through the <link +linkend="getting-started">Getting Started</link> section first so that +your setup goes smoothly.</para> + +<para>Since most people do not read documentation anyway, here is a +collection of the most helpful tips:</para> + +<itemizedlist> +<listitem> +<para>You do not have to use your mouse to use &kmail;. Everything can +be done by using <link linkend="keyboard-shortcuts">Keyboard Shortcuts</link>.</para> +</listitem> +<listitem> +<para>Although &kmail; can be considered reliable you should keep +backups of your messages, &ie; just copy the files and folders +in <filename class="directory">~/Mail</filename> +(including the hidden ones that start with a dot) to a safe place.</para> +</listitem> +<!-- TODO: add other tips for "invisible" features here --> + +</itemizedlist> + +<para>&kmail;'s homepage can be found at <ulink +url="http://kmail.kde.org">http://kmail.kde.org</ulink>. There you will +find useful links, ⪚ to the user and developer mailing lists. +Please report bugs in &kmail; using +<menuchoice><guimenu>Help</guimenu><guimenuitem>Report +Bug...</guimenuitem></menuchoice>.</para> + +<para>We hope you will enjoy &kmail;!</para> + +</chapter> diff --git a/doc/kmail/menus.docbook b/doc/kmail/menus.docbook new file mode 100644 index 000000000..ff281f053 --- /dev/null +++ b/doc/kmail/menus.docbook @@ -0,0 +1,2222 @@ +<chapter id="menus"> + +<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-11</date> +<releaseinfo>1.7</releaseinfo> +</chapterinfo> + +<title>Menu Entries</title> + +<para>Each menu item is discussed below. When there is a keyboard shortcut that +performs a menu item function, the default shortcut is listed with the menu item.</para> + +<sect1 id="main-mail-reader-window"> +<title>The Main Window</title> + +<sect2 id="reader-file-menu"> +<title><guimenu>File</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>New Window</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Creates a new main window.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo></shortcut> +<guimenu>File</guimenu> +<guimenuitem>Open...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Allows you to open files which contain email messages.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo></shortcut> +<guimenu>File</guimenu> +<guimenuitem>Save As...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Saves the currently displayed message to a text file, including all the headers +and attachments.</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>Display a dialog that lets you prints the currently displayed message.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Compact All Folders</guimenuitem> +</menuchoice></term> +<listitem> +<para>Will compact all folders, &ie; it will really move and delete the messages +on disk according to how you have moved and deleted them in &kmail;.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Expire All Folders</guimenuitem> +</menuchoice></term> +<listitem> +<para>Delete old messages from all folders, according to the rules in +each folder's <link linkend="folders-properties-window">Properties dialog</link> +(the default is not to delete old messages at all).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Refresh Local &imap; Cache</guimenuitem> +</menuchoice></term> +<listitem> +<para>This will remove all changes that you have done locally to your IMAP +folders and redownload everything from the server. Use this if the local +cache was corrupted.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Empty All Trash Folders</guimenuitem> +</menuchoice></term> +<listitem> +<para>Use this to empty all trash folders, &ie; the local trash folder and +all trash folders that you might have on &imap; servers.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>L</keycap></keycombo></shortcut> +<guimenu>File</guimenu> +<guimenuitem>Check Mail</guimenuitem> +</menuchoice> +</term> +<listitem><para>Checks for new messages in all your accounts, except those that +have <guilabel>Exclude from "Check Mail"</guilabel> enabled.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guisubmenu>Check Mail In</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>Submenu that lets you check for new messages from a particular account.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Send Queued Messages</guimenuitem> +</menuchoice></term> +<listitem> +<para>Sends the messages that are in your outbox.</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>Closes the current main window or exits +&kmail; if there is only this one window.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + + +<sect2 id="reader-edit-menu"> +<title><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>Revokes your last move or delete action. Note that you cannot undo a deletion +in the trash.</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>Copies selected text to the clipboard.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>T</keycap></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Edit Message</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Edits the selected message if it is editable. Only messages in the +<guilabel>outbox</guilabel> and <guilabel>drafts</guilabel> folder can be edited.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>Delete</keycap></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Move to Trash</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Moves the selected messages to the trash folder. If the selected +messages are already in the trash folder, they will really be deleted.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Shift;<keycap>Delete</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Delete</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Deletes the selected messages. There is no way to recover the messages +once they are deleted with this command.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Find in Message...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Lets you search for a string in the currently displayed message.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>A</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Select All Messages</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Selects all messages in the current folder.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>A</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Select Message Text</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Selects the text of the currently displayed message.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + + +<sect2 id="reader-view-menu"> +<title><guimenu>View</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Headers</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Changes the format of the message header in the <guilabel>Message pane</guilabel>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Attachments</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Changes the way attachments appear in the <guilabel>Message +pane</guilabel> (independent of the MIME Tree). With <guimenuitem>As Icons</guimenuitem> +all attachments appear as icons at the bottom of the message. +<guimenuitem>Smart</guimenuitem> will show attachments as +icons, unless the message suggests that they should be displayed inline. +You can suggest that certain attachments should be shown inline +in your own messages when you select <guilabel>Suggest automatic display</guilabel> +in the attachment's properties dialog. +<guimenuitem>Inline</guimenuitem> shows the contents of the attachments +at the bottom of the message. Attachments that cannot be displayed, ⪚ +compressed files, will still be shown as an icon. +<guimenuitem>Hide</guimenuitem> will not show attachments. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Unread Column</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Allows you to specify whether the number of unread messages should +be shown in parentheses next to the folder name (<guilabel>View After Folder +Name</guilabel>) or in a separate column (<guilabel>View in Separate +Column</guilabel>)</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Total Column</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Display a column in the list of folders which shows the number +of messages per folder.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>.</keycap></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Expand Thread</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>If <menuchoice><guimenu>Folder</guimenu><guimenuitem>Thread Messages</guimenuitem> +</menuchoice> is activated, this will display the thread of the current message, &ie; +all messages that are replies to the current message.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>,</keycap></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Collapse Thread</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>If <menuchoice><guimenu>Folder</guimenu><guimenuitem>Thread Messages</guimenuitem> +</menuchoice> is activated, this will hide the thread of the current message, &ie; +it will hide all messages that are replies to the current message.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>.</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Expand All Threads</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Expands all threads in the current folder.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>,</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Collapse All Threads</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Collapses all threads in the current folder.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>V</keycap></shortcut> +<guimenu>View</guimenu> +<guimenuitem>View Source</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Shows the message and its complete headers in plain text format in a new +window. This can be useful to find out the origin of a mail. You should know +that it is easy to fake the <literal>From:</literal> header of a mail, but +one can still find out which mail servers have been used to send the message by looking +at the <literal>Received:</literal> lines in the header.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>X</keycap></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Use Fixed Font</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Uses a fixed width (monospaced) font to display the messages +in the current folder. The font to be used can be configured in the +<guilabel>Appearance</guilabel> section of &kmail;'s configuration +dialog.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Set Encoding</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>Lets you choose the character encoding to be used in the Message +Pane. The default, <guilabel>Auto</guilabel>, should work in almost all cases.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + + +<sect2 id="reader-go-menu"> +<title><guimenu>Go</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>N</keycap></shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Next Message</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Selects the next message in the message list. The keyboard shortcut +<keycap>Right Arrow</keycap> also performs this action.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>+</keycap></shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Next Unread Message</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Selects the next unread message in the message list. If there is +no unread message below the currently selected message then the behavior +depends on the value of the <xref +linkend="configure-misc-folders-go-unread"/> option.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>P</keycap></shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Previous Message</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Selects the previous message in the message list.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>-</keycap></shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Previous Unread Message</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Selects the previous unread message in the message list. If there is +no unread message above the currently selected message then the behavior +depends on the value of the <xref +linkend="configure-misc-folders-go-unread"/> option.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>+</keycap></keycombo></shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Next Unread Folder</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Jumps to the the next folder with unread messages.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>-</keycap></keycombo></shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Previous Unread Folder</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Jumps to the the previous folder with unread messages.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>Space</keycap></shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Next Unread Text</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Scrolls down if you are not yet at the bottom of a message, otherwise +jumps to the next unread message.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + + +<sect2 id="reader-folder-menu"> +<title><guimenu>Folder</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>New Folder...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens the <link linkend="folders-properties-window">Folder Properties</link> +dialog that lets you create a new folder.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Mark All Messages as Read</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Sets the status of all new and unread messages in the current folder to read.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Compact</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Compacts the folder file to reduce its disk space usage. Usually +&kmail; compacts all folders automatically, but under certain circumstances +you might want to compact a folder manually.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Expire</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Deletes old messages from the current folder or moves them to another +folder, according to the rules in the folder's <guilabel>Properties</guilabel> dialog (the default is not to delete or move old messages). Usually &kmail; +does this automatically, but under certain circumstances you might want to +expire a folder manually..</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>*</keycap></keycombo></shortcut> +<guimenu>Folder</guimenu> +<guimenuitem>Remove Duplicate Messages</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Searches the folder for duplicate messages and deletes the +duplicates.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>F5</keycap></shortcut> +<guimenu>Folder</guimenu> +<guimenuitem>Check Mail in This Folder</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Checks whether new mail arrived in the currently selected folder. +This is only available for &imap; folders.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Troubleshoot IMAP Cache...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens a dialog that helps to solve problems with synchronizing disconnected &imap; folders. +</para> +<para><guilabel>Rebuild Index</guilabel>. As a first step to solve synchronization problems, you can rebuild the index file. This will take some time, but can not cause any problems or data loss. +You can select if the indexes should be rebuilt for the selected folder only (<guilabel>Only current folder</guilabel>), the selected folder and its folder subtree (<guilabel>Current folder and all subfolders</guilabel>), or for the whole account (<guilabel>All folders of this account</guilabel>). +</para> +<para> +<guilabel>Refresh Cache</guilabel>: +If rebuilding the index does not solve the problem, you can refresh the local IMAP cache for the current folder and all subfolders. The cache is deleted and the mails are refetched from the server. This will delete all your local changes in these folders! +</para> +<para> +This option is only available for disconnected &imap; folders. +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Move All Messages to Trash</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Moves all of the messages in the selected folder into the trash folder. +This is only available if the currently selected folder is not a trash +folder.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Empty Trash</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Permanently deletes all messages. This is only available if the +currently selected folder is a trash folder.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Delete Folder</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Removes the selected folder and all its contents, including subfolders.</para> +<warning><para>Note that there is no way to access the contents +of a folder after it has been removed.</para></warning> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Prefer HTML to Plain Text</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>If enabled then &html; messages in this folders will be shown using +&html; rendering. For security reasons, we recommend to only +activate this for folders which only contain trusted messages.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Thread Messages</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>If enabled then the messages in the message list +are shown in a tree-like list, with replies showing up directly under the +message they reply to.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Thread Messages also by Subject</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>If enabled then the messages are not only grouped according to special +information included in the messages but also according to their subject, +&ie; messages with the same subject are considered as being related. +If many messages are threaded below unrelated messages then you might want +to disable this option. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Properties</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens up the <link linkend="folders-properties-window">Properties dialog</link> which lets you +change the settings for the selected folder.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="reader-message-menu"> +<title><guimenu>Message</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></shortcut> +<guimenu>Message</guimenu> +<guimenuitem>New Message...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens the <link linkend="the-composer-window">composer window</link> so you can +write a new message.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Message</guimenu> +<guimenuitem>New Message to Mailing-List...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens the composer window so you can write a new +mail. If the current folder holds a mailing list and has a posting +address defined, this address will be the default <guilabel>To:</guilabel> +address.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>R</keycap></shortcut> +<guimenu>Message</guimenu> +<guimenuitem>Reply...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens up the composer window, inserts the quoted text of the currently +selected message and presets the <guilabel>To:</guilabel> field either with +the mailing-list address (if you reply to a mailing-list message) or with the +preferred reply address of the sender. If you want to control which address +the <guilabel>To:</guilabel> field is preset with then you should either use +<menuchoice><guimenu>Message</guimenu><guimenuitem>Reply to +Author...</guimenuitem></menuchoice> or +<menuchoice><guimenu>Message</guimenu><guimenuitem>Reply to +Mailing-List...</guimenuitem></menuchoice>. +Your identity will automatically be set to the one which this message was +sent to.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>A</keycap></shortcut> +<guimenu>Message</guimenu> +<guimenuitem>Reply to All...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens up the composer window, inserts the quoted text of the currently +selected message and presets the <guilabel>To:</guilabel> field either with +the mailing-list address (if you reply to a mailing-list message) or with the +preferred reply address of the sender. The <guilabel>Copy to (CC):</guilabel> +field is preset with the addresses of all other recipients of the currently +selected message excluding your own addresses. +Your identity will automatically be set to the one which this message was +sent to.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Shift;<keycap>A</keycap></keycombo></shortcut> +<guimenu>Message</guimenu> +<guimenuitem>Reply to Author...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens up the composer window, inserts the quoted text of the currently +selected message and presets the <guilabel>To:</guilabel> field with the +preferred reply address of the sender. +Your identity will automatically be set to the one which this message was +sent to.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>L</keycap></shortcut> +<guimenu>Message</guimenu> +<guimenuitem>Reply to Mailing-List...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens up the composer window, inserts the quoted text of the currently +selected message and presets the <guilabel>To:</guilabel> field with +the mailing-list address. If you did not specify a mailing-list address for +the currently selected folder and &kmail; cannot determine the posting address +from the currently selected message then the <guilabel>To:</guilabel> field +will be empty. +Your identity will automatically be set to the one which this message was +sent to.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Shift;<keycap>R</keycap></keycombo></shortcut> +<guimenu>Message</guimenu> +<guimenuitem>Reply Without Quote...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Works just like <guimenuitem>Reply...</guimenuitem> except that the text +of the currently selected message is not quoted.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Message</guimenu> +<guimenuitem>Forward</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Forwards the message to a new recipient. +Using <guimenuitem>As Attachment</guimenuitem> the message and its attachments +will become an attachment of the new message. The original message headers will +be included in the forwarded message, too. + +Using <guimenuitem>Inline</guimenuitem>, the message's text and some important +header fields will be copied to the body of the new message with a text marking +the forwarded part. Attachments will be forwarded as attachments of the new +message. + +<guimenuitem>As Digest</guimenuitem> concatenates the messages together as a +MIME digest attachment. + +<guimenuitem>Redirect</guimenuitem> works like forward, except that the message +stays the same (even the <guilabel>From:</guilabel> field). The user who +redirected the message is added in special header fields (<literal>Redirect-From</literal>, +<literal>Redirect-Date</literal>, <literal>Redirect-To</literal>, &etc;). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Message</guimenu> +<guimenuitem>Send Again...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens a composer window with the currently selected message so it can be +sent again. This is only available for messages which you have sent or, more +precisely, for messages which have the <guilabel>sent</guilabel> status.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Message</guimenu> +<guisubmenu>Copy To</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>Copies the selected messages to a certain folder.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Message</guimenu> +<guisubmenu>Move To</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>Moves the selected messages to a certain folder.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Message</guimenu> +<guisubmenu>Mark Message</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>Allows you to change the status of the selected message to one of the +following states:</para> +<!-- TODO: I think it is worth adding inline images here, at some point. LW. --> +<informaltable> +<tgroup cols="2"> +<thead> +<row> +<entry>Status</entry> +<entry>Symbol</entry> +<entry>Meaning</entry> +</row> +</thead> +<tbody> +<row> +<entry><guimenuitem>Read</guimenuitem></entry> +<entry>Sheet of paper before an envelope</entry> +<entry>The message has been read.</entry> +</row> +<row> +<entry><guimenuitem>New</guimenuitem></entry> +<entry>Closed envelope with a star</entry> +<entry>The message is new to &kmail; and you.</entry> +</row> +<row> +<entry><guimenuitem>Unread</guimenuitem></entry> +<entry>Close envelope</entry> +<entry>The message is not new to &kmail; but has not been read yet.</entry> +</row> +<row> +<entry><guimenuitem>Important</guimenuitem></entry> +<entry>Flag</entry> +<entry>This status will not automatically be set by &kmail;. You can use it freely to mark +messages that are in some way important to you.</entry> +</row> +<row> +<entry><guimenuitem>Replied</guimenuitem></entry> +<entry>Blue u-turn arrow</entry> +<entry>A reply to this message has been sent.</entry> +</row> +<row> +<entry><guimenuitem>Forwarded</guimenuitem></entry> +<entry>Blue arrow</entry> +<entry>The message has been forwarded to someone else.</entry> +</row> +<row> +<entry><guimenuitem>Queued</guimenuitem></entry> +<entry>Envelope</entry> +<entry>The message has been queued in the outbox to be sent later.</entry> +</row> +<row> +<entry><guimenuitem>Sent</guimenuitem></entry> +<entry>Angled envelope</entry> +<entry>The message has been sent.</entry> +</row> +<row> +<entry><guimenuitem>Spam</guimenuitem></entry> +<entry>Round recycle symbol</entry> +<entry>This status will not be set automatically by &kmail;. You can use it +to mark spam messages.</entry> +</row> +<row> +<entry><guimenuitem>Ham</guimenuitem></entry> +<entry>Green check mark</entry> +<entry>This status will not be set automatically by &kmail;. You can use it +to mark messages which are not spam.</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Message</guimenu> +<guisubmenu>Mark Thread</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>Allows you to change the status of all messages in a thread. The possible +states are the same as for <menuchoice><guimenu>Message</guimenu> +<guimenuitem>Mark Message</guimenuitem></menuchoice>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Message</guimenu> +<guisubmenu>Watch Thread</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>Use this to mark threads which you want to keep an eye on for further +contributions to the discussion.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Message</guimenu> +<guisubmenu>Ignore Thread</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>Use this to mark threads you are not interested in. New contributions +to this thread will automatically be marked as read.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Message</guimenu> +<guisubmenu>Create Filter</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>Opens up the <link linkend="filter-dialog-id">Filter dialog</link> with a new filter added. +This new filter is based on fields of the current mail, depending on which +sub menu item you select.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>J</keycap></keycombo></shortcut> +<guimenu>Message</guimenu> +<guimenuitem>Apply Filters</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Applies your filters to the selected messages.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Message</guimenu> +<guimenuitem>Apply Filter</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Allows you to apply an individual filter to the selected messages. Only +filters for which you enabled the <guilabel>Add this filter to the Apply +Filter menu</guilabel> option will be available.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + + +<sect2 id="reader-tools-menu"> +<title><guimenu>Tools</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>S</keycap></shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Find Messages...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens up a search window that lets you search for messages with +certain characteristics, ⪚ a certain subject. Start the search by entering +some values and press <guibutton>Search</guibutton>. Click on one of the +resulting messages and it will appear in the <guilabel>Message +pane</guilabel>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Address Book</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Starts up <ulink url="/kaddressbook/">&kaddressbook;</ulink>, +the &kde; address book.</para> +</listitem> +</varlistentry> + + <varlistentry id="reader-tools-certificate-manager"> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Certificate Manager...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Starts <ulink + url="/kleopatra"><application>Kleopatra</application></ulink>, + the &kde; certificate manager. + </para> + </listitem> + </varlistentry> + + <varlistentry id="reader-tools-gnupg-log-viewer"> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>GnuPG Log Viewer</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Starts <ulink + url="/kwatchgnupg"><application>KWatchGnuPG</application></ulink>, + a tool to present the debug output of + <application>GnuPG</application> application. If + signing, encryption, or verification mysteriously stop + working, you might find out why by looking at the log. + </para> + </listitem> + </varlistentry> + + <varlistentry id="reader-tools-import-messages"> + <term> + <menuchoice> + <guimenu>Tools</guimenu> + <guimenuitem>Import Messages...</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + Starts up <application>kmailcvt</application> (which is + part of kdepim). This application lets you import + messages from several email clients &kmail;. + </para> + </listitem> + </varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Tools</guimenu> +<guisubmenu>Edit "Out of Office" Replies...</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>Launch the <guilabel>Configure "Out of Office" Replies</guilabel> dialog, which allow you to set-up vacation notifications.</para> +<note> +<para><guilabel>Out of Office reply</guilabel> functionality relies on server-side filtering. To be able to use it you need to configure the <link linkend="receiving-mail">Filtering tab</link> (see option relevant to kolab server) of your <guilabel>IMAP</guilabel> account set-up. +</para> +</note> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Tools</guimenu> +<guisubmenu>Filter Log Viewer...</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>Opens up the viewer window for the filter log; there you find some options to +control the logging of the filtering process. In the log you will find valuable +information about what filter rules were used, what was the result of the evaluation +of those rules, and which filter actions were applied to a message.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Anti-Spam Wizard...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>It starts a <link linkend="the-anti-spam-wizard">wizard</link> which can help +you to set up spam filtering.</para> +</listitem> +</varlistentry> + +<!-- +<varlistentry> +<term> +<menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Anti-Virus Wizard...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>It starts a <link linkend="the-anti-virus-wizard">wizard</link> which can help +you to set up scanning messages for viruses.</para> +</listitem> +</varlistentry> +--> + +</variablelist> + +</sect2> + + +<sect2 id="reader-settings-menu"> +<title><guimenu>Settings</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Show Toolbar</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>If enabled, the Toolbar is visible (the Toolbar is the one with the icon +to compose a new message &etc;).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Show Quick Search</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>If enabled, the Quick Search bar which allows you to quickly search +for messages matching a search text is visible.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Filters...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens the <link linkend="filters">Message Filters</link> window.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure POP Filters...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens the <link linkend="popfilters">Configure Pop Filters</link> window.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Shortcuts...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens a window that lets you configure the keyboard shortcuts for many +menu commands.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Notifications...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens a window that lets you configure what happens when new mail arrives, +like playing a sound.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Toolbars...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens a window that lets you choose which icons are visible in the +toolbar.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure &kmail;...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens the <link linkend="configure">Configure</link> window.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="reader-help-menu"> +<title><guimenu>Help</guimenu> Menu</title> + +<para>These are the &kde; standard items for the <guimenu>Help</guimenu> menu:</para> + +&help.menu.documentation; + +<para>Additionally &kmail; offers these items:</para> + +<variablelist> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Help</guimenu> +<guimenuitem>&kmail; Introduction</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>This displays the welcome screen, which lists the most important +differences between your version of &kmail; and the previous one.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Help</guimenu> +<guimenuitem>Tip of the Day</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>This displays a dialog with useful hints for using &kmail;.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> +</sect1> + +<sect1 id="composer-window-menus"> +<title>The Composer Window</title> + +<sect2 id="composer-file-menu"> +<title><guimenu>Message</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></shortcut> +<guimenu>Message</guimenu> +<guimenuitem>New Composer</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens up a new composer window.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Message</guimenu> +<guimenuitem>New Main Window</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Creates a new main window.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>Return</keycap></keycombo></shortcut> +<guimenu>Message</guimenu> +<guimenuitem>Send Now</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Sends the message immediately. If you use SMTP to send your +messages and the SMTP server is not reachable, the message will be put +into the outbox and you will get an error message. You can then later send +the messages in the outbox using <menuchoice><guimenu>File</guimenu><guimenuitem>Send +Queued Messages</guimenuitem></menuchoice>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Message</guimenu> +<guimenuitem>Send Later</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Queues the message in the outbox for sending it later using +<menuchoice><guimenu>File</guimenu><guimenuitem>Send +Queued Messages</guimenuitem></menuchoice>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Message</guimenu> +<guimenuitem>Save in Drafts Folder</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Save the message in the <guilabel>drafts</guilabel> folder so you can +later edit and send it.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Messages</guimenu> +<guimenuitem>Insert File...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Inserts a text file into the message text, starting at the cursor +position.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo></shortcut> +<guimenu>Message</guimenu> +<guimenuitem>Print...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Prints the current text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo></shortcut> +<guimenu>Message</guimenu> +<guimenuitem>Close</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Closes this composer window.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + + +<sect2 id="composer-edit-menu"> +<title><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>Undo your steps in editing the current message.</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>Redo your steps in editing the current message.</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>Cutting text works as with most editors: the selected text is +removed and put into the clipboard. Note that you can also select text and +drag it to a new position.</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>Copying text works as with most editors: the selected text is copied to the clipboard. +Note that you can also select text while holding the &Ctrl; key, and drag it to a new +position to copy it.</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>Pasting works the same as with most editors: the text from the +clipboard is pasted at the current cursor position.</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>Selects all of the text in your message.</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>Opens a dialog to search for strings in the current message.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Find Next</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Goes to the next occurrence of the previously searched string.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Replace...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens a dialog that lets you replace strings in your message with other strings.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Clean Spaces</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>This replaces multiple line breaks or spaces with single line breaks or spaces. +It works on the current selection or on the complete message if there is no selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Paste as Quotation</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Pastes the text from the clipboard marked as quotation.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Add Quote Characters</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Prepends the selected text with quotation marks.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Remove Quote Characters</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Removes the left-most quotation marks from the selected text.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="composer-view-menu"> +<title><guimenu>View</guimenu> Menu</title> + +<para>This menu lets you toggle the display of the header fields and other +options in this composer window.</para> + +<para>Options available are:</para> + +<itemizedlist> +<listitem> +<para><guimenuitem>All Fields</guimenuitem></para> +</listitem> +<listitem> +<para><guimenuitem>Identity</guimenuitem></para> +</listitem> +<listitem> +<para><guimenuitem>Dictionary</guimenuitem></para> +</listitem> +<listitem> +<para><guimenuitem>Sent-Mail folder</guimenuitem></para> +</listitem> +<listitem> +<para><guimenuitem>Mail Transport</guimenuitem></para> +</listitem> +<listitem> +<para><guimenuitem>From</guimenuitem></para> +</listitem> +<listitem> +<para><guimenuitem>Reply To</guimenuitem></para> +</listitem> +<listitem> +<para><guimenuitem>To</guimenuitem></para> +</listitem> +<listitem> +<para><guimenuitem>CC</guimenuitem></para> +</listitem> +<listitem> +<para><guimenuitem>BCC</guimenuitem></para> +</listitem> +<listitem> +<para><guimenuitem>Subject</guimenuitem></para> +</listitem> +</itemizedlist> + +<para>Currently visible items have a checkmark shown next to their name in the +menu.</para> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Use Fixed Font</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Uses a fixed width (monospaced) font to display the currently +edited message. The font to be used can be configured in the +<guilabel>Appearance</guilabel> section of &kmail;'s configuration +dialog.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="composer-options-menu"> +<title><guimenu>Options</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Options</guimenu> +<guimenuitem>Urgent</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Sets the priority of the message to Urgent. The receiver's email client has to support +this or it will have no effect. &kmail; itself does not support priorities for +incoming messages.</para> +</listitem> +</varlistentry> + + <varlistentry id="composer-options-request-mdn"> + <term> + <menuchoice> + <guimenu>Options</guimenu> + <guimenuitem>Request Disposition Notification</guimenuitem> + </menuchoice> + </term> + <listitem> + <para> + If you choose this option, you request a confirmation + email once your message is downloaded and read by its + recipient. This has to be supported and enabled by the + receiver's email client in order to work. + </para> + <para> + See <xref linkend="configure-security-reading-mdns"/> + for background information and ways to customize the + read receipts that &kmail; itself sends. + </para> + </listitem> + </varlistentry> + +<varlistentry id="composer-options-sign-message"> +<term> +<menuchoice> +<guimenu>Options</guimenu> +<guisubmenu>Sign Message</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>Digitally sign the message using <application>OpenPGP</application>. +You can learn more about this in the <link linkend="pgp">chapter on OpenPGP</link>.</para> +</listitem> +</varlistentry> + +<varlistentry id="composer-options-encrypt-message"> +<term> +<menuchoice> +<guimenu>Options</guimenu> +<guisubmenu>Encrypt Message</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>Encrypt the message using <application>OpenPGP</application>. +You can learn more about this in the <link linkend="pgp">chapter on OpenPGP</link>.</para> +</listitem> +</varlistentry> + + <varlistentry id="composer-options-select-crypto-message-format"> + <term> + <menuchoice> + <guimenu>Options</guimenu> + <guisubmenu>Select Cryptographic Message Format</guisubmenu> + </menuchoice> + </term> + <listitem> + <para> + Choose the cryptographic message format to use to + digitally sign and/or encrypt the message in. See <link + linkend="cryptographic-message-formats">the previous + description of each option</link> for more information. + </para> + </listitem> + </varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Options</guimenu> +<guisubmenu>Formatting (HTML)</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>Enables &html; editing.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Options</guimenu> +<guisubmenu>Set Encoding</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>Set the charset encoding of this message. The chosen encoding will appear in the header of +the outgoing mail. You can use <guilabel>Auto</guilabel> for almost all +cases, &kmail; will tell you if you need to select a different encoding manually.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Options</guimenu> +<guimenuitem>Wordwrap</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Toggles the automatic wordwrap. It may be useful to turn it off if you want +to paste long lines that should not wrap.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Options</guimenu> +<guimenuitem>Automatic Spellchecking</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Toggles automatic spellchecking. Note that in &html;-editing mode +automatic spellchecking is not available.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + + +<sect2 id="composer-attach-menu"> +<title><guimenu>Attach</guimenu> Menu</title> + +<para>This menu lets you select attachment options.</para> + +<variablelist> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Attach</guimenu> +<guimenuitem>Append Signature</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Appends your signature (<quote>footer</quote>) to the end of the message. +<!-- fixme: nothing to do with crypto stuff --></para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Attach</guimenu> +<guimenuitem>Attach Public Key...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Attaches the corresponding <application>PGP</application>/<application>GnuPG</application> +key to your message.</para> +</listitem> +</varlistentry> + +<varlistentry id="composer-attach-attach-my-public-key"> +<term> +<menuchoice> +<guimenu>Attach</guimenu> +<guimenuitem>Attach My Public Key</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Attaches your <application>PGP</application>/<application>GnuPG</application> +public key to your message.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Attach</guimenu> +<guimenuitem>Attach File...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Attaches one or more files to the current message.</para> +<!-- fixme: not encrypted unless... --> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Attach</guimenu> +<guimenuitem>Remove Attachment</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Removes the attachment that is selected in the attachment part of the composer.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Attach</guimenu> +<guimenuitem>Save Attachment As...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Saves the attachment that is selected in the attachment window to a +file.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Attach</guimenu> +<guimenuitem>Attachment Properties</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Displays the <link linkend="attachments">properties of the attachment</link> that is selected in the +attachment window.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="composer-tools-menu"> +<title><guimenu>Tools</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Spelling...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Uses <ulink url="/kspell/">&kspell;</ulink> to check the spelling in the body of your +message. Note that +you have to configure &kspell; with <menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Spellchecker...</guimenuitem></menuchoice> if you use it for the +first time.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Addressbook...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens up <ulink url="/kaddressbook/">&kaddressbook;</ulink>.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="composer-settings-menu"> +<title><guimenu>Settings</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Show Main Toolbar</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>If enabled, the Main Toolbar is visible, &ie; the one with the icon +to send the message &etc;.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Show HTML Toolbar</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>If enabled, the &html; Toolbar is visible, &ie; the one which with the +tools to change certain properties of the composed text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Spellchecker...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Allows you to configure <ulink url="/kspell/">&kspell;</ulink>, &kde;'s spellchecker.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Shortcuts...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens a window that lets you configure the keyboard shortcuts for many +menu commands.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Toolbars...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens a window that allows you to decide which icons appear in the +toolbar.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure &kmail;...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens &kmail;'s <link linkend="configure">configuration dialog</link>.</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + + +<sect2 id="composer-help-menu"> +<title><guimenu>Help</guimenu> Menu</title> + +<para>The entries in this menu have the same meaning as <link +linkend="reader-help-menu">the entries in the main window's help +menu</link>.</para> + +</sect2> +</sect1> + +</chapter> diff --git a/doc/kmail/using-kmail.docbook b/doc/kmail/using-kmail.docbook new file mode 100644 index 000000000..1d3b3e381 --- /dev/null +++ b/doc/kmail/using-kmail.docbook @@ -0,0 +1,2303 @@ +<chapter id="using-kmail"> + +<chapterinfo> +<authorgroup> +<author> +<firstname>Daniel</firstname> +<surname>Naber</surname> +<affiliation><address> +<email>daniel.naber@t-online.de</email> +</address></affiliation> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +<date>2004-09-24</date> +<releaseinfo>1.7.50</releaseinfo> +</chapterinfo> + +<title>Using &kmail;</title> + +<sect1 id="the-mail-reader-window"> +<title>The Main Window</title> + +<para>The main window is the window that appears +when &kmail; is started. It is by default divided into three panes:</para> + +<variablelist> +<varlistentry> +<term>Folder list (on the left)</term> +<listitem> +<para>This pane contains the list of your message folders (other email programs +may call them mailboxes). To select a folder, simply click on +it. The messages contained in the folder will now appear in the Headers +pane. The folder list can be displayed in both a short view, which takes up only +a small portion of the left side of the screen, and a long view, which takes up the +entire left side of the screen but is able to show more mailboxes. You can toggle +between these two views under <guilabel>Appearance</guilabel>/<guilabel>Layout</guilabel> +in the <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +&kmail;...</guimenuitem></menuchoice> dialog. Also see the <link +linkend="folders">Folders Section</link> for more information about how to use +folders.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Message list (in the upper right by default)</term> +<listitem> +<para>This pane lists header information (message Status Flags, Sender, Subject, +Date, and other optional columns like Size, Attachment Flag, Important Flag, etc.) +for the messages in the currently selected folder. Clicking on a header +will select that message and display it in the Message pane; you can also select +more than one message by holding down the &Ctrl; key when clicking on messages. +You may sort the messages by clicking on the column that you wish to +sort; if you click on the same column more than once, sort order will toggle +between ascending/descending and some alternative sorting criteria will become +available (like sorting by Status when you click on the header of the Subject column). +Clicking the <mousebutton>right</mousebutton> mousebutton on the list header shows a popup menu, +which allows to show or hide several columns in the list. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Message preview pane (in the lower right by default)</term> +<listitem> +<para>This pane displays the currently selected message. Attachments appear +at the bottom of the message, either as icons or embedded in the message, +depending on <menuchoice><guimenu>View</guimenu> +<guimenuitem>Attachments</guimenuitem></menuchoice>. For complex messages +the structure of the message is shown in the message structure viewer below +the preview pane. The placement of the preview pane as well as the placement +of the structure viewer can be changed under <guilabel>Appearance</guilabel>/<guilabel>Layout</guilabel> +in the <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +&kmail;...</guimenuitem></menuchoice> dialog. Moreover, you can disable the +preview pane and you can choose when the message structure viewer should be +shown. +You can scroll through the message page-by-page +using the <keycap>Page Up</keycap> and <keycap>Page down</keycap> keys, or +line-by-line using the <keycap>up arrow</keycap> and <keycap>down arrow</keycap> +keys; you can also use <link linkend="keyboard-shortcuts">key shortcuts</link> to skip through +your messages without having to use the mouse.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Font type and font size</term> +<listitem> +<para>Font type and font size buttons in main toolbar in the message reader window ( window that appears when an message is double clicked or enter is pressed on the message ) will change the font type or font size of the whole text of the email message in concern. This property is transient ( per email message ) and will be lost when the reader window is closed.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Delete Attachment</term> +<listitem> +<para>Right click on the attachment either in the message itself or in the message structure window, choose "Delete Attachment" to delete the attachement. Please note that deleting an attachment can invalidate any digital signature in the message.</para> +</listitem> +</varlistentry> +</variablelist> +</sect1> + +<sect1 id="keyboard-shortcuts"> +<title>Keyboard Shortcuts</title> + +<para>The following keyboard shortcuts are supported in the main window:</para> + +<informaltable> +<tgroup cols="2"> +<thead> +<row> +<entry>Keyboard Shortcut</entry> +<entry>Action</entry> +</row> +</thead> +<tbody> +<row> +<entry><keycap>Space</keycap></entry> +<entry>Scroll down in the current message or go to the next unread message if you are already +at the bottom.</entry> +</row> +<row> +<entry><keycap>Right Arrow</keycap> or <keycap>N</keycap></entry> +<entry>Go to the next message in the current folder.</entry> +</row> +<row> +<entry><keycap>Left Arrow</keycap> key or <keycap>P</keycap></entry> +<entry>Go to the previous message in the current folder.</entry> +</row> +<row> +<entry><keycap>+</keycap></entry> +<entry>Go to the next unread message in the current folder.</entry> +</row> +<row> +<entry><keycap>-</keycap></entry> +<entry>Go to the previous unread message in the current folder.</entry> +</row> +<row> +<entry><keycombo action="simul">&Ctrl;<keycap>+</keycap></keycombo></entry> +<entry>Go to the next folder with unread messages.</entry> +</row> +<row> +<entry><keycombo action="simul">&Ctrl;<keycap>-</keycap></keycombo></entry> +<entry>Go to the previous folder with unread messages.</entry> +</row> +<row> +<entry><keycombo action="simul">&Ctrl;<keycap>Up Arrow</keycap></keycombo></entry> +<entry>Go to the next folder in the folder list (if the folder list has focus.)</entry> +</row> +<row> +<entry><keycombo action="simul">&Ctrl;<keycap>Down Arrow</keycap></keycombo></entry> +<entry>Go to the previous folder in the folder list (if the folder list has focus.)</entry> +</row> +<row> +<entry><keycombo action="simul">&Ctrl;<keycap>Left Arrow</keycap></keycombo></entry> +<entry>Walk upwards in the list of folders. Use +<keycombo action="simul">&Ctrl;<keycap>Space</keycap></keycombo> to actually +enter the folder.</entry> +<!-- TODO: or wait for timeout so the folder is selected? --> +</row> +<row> +<entry><keycombo action="simul">&Ctrl;<keycap>Right Arrow</keycap></keycombo></entry> +<entry>Walk downwards in the list of folders. Use +<keycombo action="simul">&Ctrl;<keycap>Space</keycap></keycombo> to actually +enter the folder.</entry> +</row> +<row> +<entry><keycombo action="simul">&Ctrl;<keycap>Space</keycap></keycombo></entry> +<entry>Enter the folder that has focus, &ie; the folder that you navigated +to using <keycombo action="simul">&Ctrl;<keycap>Left Arrow</keycap></keycombo> or +<keycombo action="simul">&Ctrl;<keycap>Right Arrow</keycap></keycombo>.</entry> +</row> +<row> +<entry><keycombo action="simul">&Shift;<keycap>Left Arrow</keycap></keycombo> and +<keycombo action="simul">&Shift;<keycap>Right Arrow</keycap></keycombo></entry> +<entry>Select messages in the header pane, starting with the current message.</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para>For more keyboard shortcuts have a look at the <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Shortcuts...</guimenuitem></menuchoice> dialog.</para> + +</sect1> + +<sect1 id="the-composer-window"> +<title>The Composer Window</title> + +<para>The composer window is used to write new messages; +it can be invoked via <menuchoice><guimenu>Message</guimenu> +<guimenuitem>New Message...</guimenuitem></menuchoice> +menu or from the <guiicon>New Message</guiicon> icon on the main +window.</para> + +<sect2 id="composing-a-message"> +<title>Composing a Message</title> + +<para>To write your message, fill in the appropriate fields in the +composer window. Use the <guimenu>View</guimenu> menu +to select which header fields are displayed. The <guimenuitem>Identity</guimenuitem> +field offers a <guibutton>Sticky</guibutton> option; if it is checked, +the current identity will become the default identity when you open +a new composer next time.</para> + +<para>There are a variety of shortcuts to help +you with writing your messages. The <guibutton>...</guibutton> buttons next to +the <guilabel>To:</guilabel>, <guilabel>CC:</guilabel>, and +<guilabel>BCC:</guilabel> fields will call up the address book so that you can +select addresses from there.</para> + +<para>When you start typing an address in the +<guilabel>To:</guilabel>/<guilabel>CC:</guilabel>/<guilabel>BCC:</guilabel> +fields, a popup will appear that offers matching addresses that have been used recently +and matching addresses from your address book. If you use multiple addressbooks, you can +use the TAB key to select the first entry of the next addressbook in the list. +If you do not like the automatic popup you can disable it by clicking with the &RMB; on the field and choosing +a different completion mode.</para> + +<para>Whenever you want to add more than one +recipient in one of the fields, use a comma to separate each address +from the next one. +<!-- fixme: there's now a setting for this: --> +You may need to specify fully qualified addresses +(&ie; <userinput>user@example.com</userinput>) even for local +users, depending on your system configuration.</para> + +<para>When you are finished with your +message, click the <guiicon>Send Now</guiicon> icon (the envelope) to send +the message now, or click the <guiicon>Send Later</guiicon> icon to put +the message in the outbox. If your message is not finished yet, select +<menuchoice><guimenu>Message</guimenu><guimenuitem>Save in Drafts +Folder</guimenuitem></menuchoice>. +</para></sect2> + +<sect2 id="encrypt-sign"> +<title>Signing and Encrypting Messages</title> + +<para> + If you want to send an <link +linkend="pgp-encrypt-your-messages">encrypted</link> +or <link linkend="pgp-sign-your-messages">digitally signed</link> message, select the +<guiicon>Sign Message</guiicon> or <guiicon>Encrypt +Message</guiicon> icons in the toolbar. Moreover you can select the format that should be used to sign and/or encrypt the message. Depending on the +installed encryption programs you can choose between: +</para> + +<variablelist id="cryptographic-message-formats"> +<varlistentry> +<term><guilabel>Any</guilabel></term> +<listitem> +<para>&kmail; will use a format which is understood by all recipients of the +message. The preferred format of the recipients can be specified in the +KDE Address Book.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Inline OpenPGP (deprecated)</guilabel></term> +<listitem> +<para>This format is outdated. If you use this format then only the +message text will be signed and/or encrypted. <emphasis>Attachments will +neither be signed nor encrypted.</emphasis> HTML messages cannot be signed +with this format. You should only use this format +if necessary, &ie; if you send messages to users of email clients that cannot +handle the more advanced formats.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>PGP/MIME</guilabel></term> +<listitem> +<para>This format is the successor of the inline OpenPGP format. If you +use this format then the message text and all attachments will be signed +and/or encrypted (at least by default). This is the recommended format if you +use OpenPGP.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>S/MIME</guilabel></term> +<listitem> +<para>This format is an alternative format to PGP/MIME. If you +use this format then the message text and all attachments will be signed +and/or encrypted (at least by default). This format is mostly used by +corporations.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>S/MIME opaque</guilabel></term> +<listitem> +<para>This format is a variant of the S/MIME format. It should only be +used if necessary.</para></listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="html-mails"> +<title>Creating HTML Messages</title> + +<para>Note that HTML messages are often regarded as an annoyance; therefore, +you should avoid sending HTML messages if possible. Particularly, you should never +send HTML messages to a mailing list unless HTML messages are explicitly +allowed.</para> + +<para>In order to be able to create HTML messages you first have to enable +the markup tools. To do this enable <guimenuitem>Formatting (HTML)</guimenuitem> in the <menuchoice><guimenu>Options</guimenu></menuchoice> menu. +A toolbar with several tools to +format the message will appear. Via the drop down box you can select between +standard text and six different types of lists (three bulleted lists with +different symbols and three numbered lists with different numbering). +Moreover, you can select the font family, the font size, the font style (bold, +italic, underlined) and the text color. Last but not least, you can select +the alignment of the text (left aligned, centered, right aligned).</para> + +<para>Creating tables and embedding images is currently not possible.</para> + +</sect2> + +<sect2 id="attachments"> +<title>Adding Attachments</title> + +<para>You can attach files to your message by using one of the methods +below:</para> + +<itemizedlist> +<listitem> +<para>Click the <guiicon>Attach File</guiicon> (paper clip) icon and select the file you wish +to attach;</para> +</listitem> +<listitem> +<para>Drag a file from the desktop or another folder into the +composer window;</para> +</listitem> +<listitem> +<para>Drag a message from &kmail;'s message list into the composer +window -- that message will then be attached;</para> +</listitem> +<listitem> +<para>Select one of the options in the +<menuchoice><guimenu>Attach</guimenu></menuchoice> menu.</para> +</listitem> +</itemizedlist> + +<para>Once a file is attached to your message, it appears in the attachments +pane at the bottom of the composer window. You can use the +&RMB; on each attachment to <guimenuitem>View</guimenuitem>, +<guimenuitem>Save</guimenuitem> or <guimenuitem>Remove</guimenuitem> +the attachment.</para> + +<para>Use the <guimenuitem>Properties</guimenuitem> item to +open the <guilabel>Message Part Properties</guilabel> dialog. +The first field contains the attachment's &MIME; type. Just like the <guilabel>Name</guilabel> +field, it should be automatically filled with an appropriate value. Sometimes the +&MIME; type value may be wrong. You can then type in any &MIME; type or +choose from the list of common &MIME; types. You can also select an encoding +method for your file from the list of encoding options (normally, the default +value works fine). Check the <guilabel>Suggest automatic display</guilabel> option +if you want to suggest to the recipient the automatic (inline) display of this attachment. Whether this works or not depends on the recipient's email client +and on his settings.</para> + +<para>You can also attach public keys to the message by using the appropriate options in the +<menuchoice><guimenu>Attach</guimenu></menuchoice> menu. <application>PGP</application> +key attachments are handled like file attachments.</para> + +</sect2> + +<sect2 id="checking-the-spelling-of-your-message"> +<title>Checking the Spelling of your Message</title> + +<para>&kmail; will automatically check the spelling of your message (in +HTML mode this currently does not work) +and display unknown words using red color. If there are too many +unknown words &kmail; will disable its checking. To select the language +used for checking, select <menuchoice><guimenu>View</guimenu> +<guimenuitem>Dictionary</guimenuitem></menuchoice>. You can disable +automatic spellchecking in the <menuchoice><guimenu>Options</guimenu></menuchoice> menu.</para> + +<para>To check the spelling of your message using a dialog, select +<menuchoice><guimenu>Tools</guimenu> +<guimenuitem>Spelling...</guimenuitem></menuchoice>. &kmail; uses +<ulink url="/kspell/">&kspell;</ulink> to +check spelling, which is the &kde; frontend to the +<application>ispell</application> or <application>aspell</application> spelling +checker. Note that you may first need to configure the spellchecker using +<menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Spellchecker...</guimenuitem></menuchoice>.</para> + +</sect2> + +</sect1> + +<sect1 id="folders"> +<title>Message Folders</title> + +<para>Message Folders are used to organize your email messages. By default, +if you have no existing message folders, messages are stored in the folder +<filename +class="directory">$<envar>KDEHOME</envar>/share/apps/kmail/</filename>. If +you have existing message folders in <filename +class="directory">~/Mail</filename>, these will be used instead. When you +first start &kmail; the <guilabel>inbox</guilabel>, +<guilabel>outbox</guilabel>, <guilabel>sent-mail</guilabel>, +<guilabel>trash</guilabel> and <guilabel>drafts</guilabel> folders are +created. These folders each have special functions:</para> + +<variablelist> +<varlistentry> +<term><guilabel>inbox:</guilabel></term> +<listitem> +<para>Where &kmail; by default puts your new messages when you ask it to check your +mail. </para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>outbox:</guilabel></term> +<listitem> +<para>Where messages are put while they are waiting to be delivered. Note that +you should not drag and drop messages here to send them, use the <guiicon>Send</guiicon> +icon in the composer window instead.<!-- fixme 3.2: has this been 'fixed'? --></para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>sent-mail:</guilabel></term> +<listitem> +<para>By default copies of all messages that you have sent are put into this folder.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>trash:</guilabel></term> +<listitem> +<para>By default all messages that you have moved to trash are moved into this folder.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>drafts:</guilabel></term> +<listitem> +<para>Contains messages you started to edit but then saved to this +folder instead of sending them.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>You may find that the standard folders are fine for your +needs; eventually, though, you will probably need folders to help you organize +your messages. To create a new folder, select +<menuchoice><guimenu>Folder</guimenu><guimenuitem>New Folder...</guimenuitem></menuchoice>: +the <link linkend="folders-properties-window">folder properties</link> dialog +will then prompt you for the necessary information. If you ever need to change +the settings for a folder, select the folder you wish to modify in the Folders pane and select +<menuchoice><guimenu>Folder</guimenu><guimenuitem>Properties</guimenuitem> +</menuchoice>.</para> + +<para>To move messages from one folder into another, select the message(s) you +want to move and press the <keycap>M</keycap> key or select +<menuchoice><guimenu>Message</guimenu><guimenuitem>Move +To</guimenuitem></menuchoice>. A list of folders will appear; select the folder +from the list that you want to move the messages to. Messages can also be moved +by dragging them from the Message list to a folder in the Folder list.</para> + +<para>If you want to clear all of the messages out of a folder choose +<menuchoice><guimenu>Folder</guimenu><guimenuitem>Move All Messages to +Trash</guimenuitem></menuchoice>. You can use +<menuchoice><guimenu>Folder</guimenu><guimenuitem>Delete Folder</guimenuitem></menuchoice> +to remove a folder and all its messages and subfolders.</para> + +<para>Folders can be copied or moved by using either drag and drop or the <menuchoice> +<guimenuitem>Copy Folder</guimenuitem></menuchoice> and <menuchoice> +<guimenuitem>Move Folder</guimenuitem></menuchoice> context menu entries. Note that you cannot +move the above listed special folders. +</para> + +<sect2 id="folders-properties-window"> +<title>Folder Properties</title> + +<para>The folder's <guilabel>Properties</guilabel> dialog lets you rename and move +a folder and specify all of its properties. Note that most properties +are only available for your own folders and not for default folder like +<guilabel>inbox</guilabel> &etc;. Default folders also cannot be moved +or renamed.</para> + +<sect3 id="folders-properties-general"> +<title>General</title> + +<para>Rename a folder by changing the entry in the <guilabel>Name:</guilabel> field.</para> + +<para>You can make a folder a subfolder of another folder by choosing a new parent +folder using the <guilabel>Belongs to</guilabel> selection. </para> + +<para>The <guilabel>Folder Icons</guilabel> section lets you choose +icons that are different from the default ones in the folder list.</para> + +<para>See the <link linkend="folders-format">Folder Format</link> section +for information about the <guilabel>Mailbox format.</guilabel></para> + +<para>With the <guilabel>Identity</guilabel> section you can set the default +identity that should be used for new messages if this folder is selected. +Replies to messages that were sent directly +to you will still default to the message's <quote>To</quote> address if an +according identity is found.</para> + +<para>With <guilabel>Show Sender/Receiver</guilabel> you can set the +visible columns in the header pane. This is useful if you use a +folder to save your own sent messages.</para> + +<para>Check <guilabel>Ignore new mail in this folder</guilabel> if you do not +want to be informed about new mail that arrives in this folder. This is for +example useful for the folder where you move all detected spam messages to.</para> + +<para>Check <guilabel>Keep replies in this folder</guilabel> if you want +replies to messages in this folder to be filed also into this folder rather +than into a special sent-mail folder.</para> + +<para>For calendar folders you can select who should get reminders for the contained +events by using the <guilabel>Generate free/busy and activate alarms for</guilabel> +choice box.</para> + +<para>In case you don't want to receive reminders for folders shared by someone else, +you can block them locally by activating the <guilabel>Block free/busy and alarms locally</guilabel> +checkbox.</para> + +</sect3> + +<sect3 id="folders-properties-expiry"> +<title>Old Message Expiry</title> + +<para>Here you can select what should happen with old messages in this +folder. If you enable <guilabel>Expire old messages in this folder</guilabel> +then &kmail; will regularly, depending on your choice, either delete old +messages or move old messages to another folder. You can also start +expiration of old messages manually via <menuchoice><guimenu>Folder</guimenu><guisubmenu>Expire</guisubmenu></menuchoice> and via +<menuchoice><guimenu>File</guimenu><guisubmenu>Expire +All Folders</guisubmenu></menuchoice></para> + +<warning><para>Messages that are deleted during expiration of old messages +cannot be restored, so be careful with this setting.</para></warning> + +</sect3> + +<sect3 id="folders-properties-mailinglist"> +<title>Mailing List</title> + +<para>If you are going to use the folder for a mailing list then you should +check <guilabel>Folder holds a mailing list</guilabel> to associate this folder +with the mailing list. Next you should +click on <guilabel>Detect Automatically</guilabel>. &kmail; will then try +to guess some information about the mailing list from the currently selected +message. If &kmail; could not determine some addresses then you can add +the missing information manually. To do this first select the +<guilabel>Address type</guilabel> for which you want to add an address. +You can choose between:</para> + + <variablelist> + <varlistentry id="folders-properties-mailinglist-post"> + <term> + <guilabel>Post to List</guilabel> + </term> + <listitem> + <para> + This address is used for sending messages to the + mailing list. This is usually an email address. + </para> + </listitem> + </varlistentry> + <varlistentry id="folders-properties-mailinglist-subscribe"> + <term> + <guilabel>Subscribe to List</guilabel> + </term> + <listitem> + <para> + This address is used for subscribing to the mailing + list. This can be an email address or the address of a + webpage. + </para> + </listitem> + </varlistentry> + <varlistentry id="folders-properties-mailinglist-unsubscribe"> + <term> + <guilabel>Unsubscribe from List</guilabel> + </term> + <listitem> + <para> + This address is used for unsubscribing from the + mailing list. This can be an email address or the + address of a webpage. + </para> + </listitem> + </varlistentry> + <varlistentry id="folders-properties-mailinglist-archive"> + <term> + <guilabel>List Archives</guilabel> + </term> + <listitem> + <para> + This is the address of the archive of the mailing + list. This is usually the address of a webpage. + </para> + </listitem> + </varlistentry> + <varlistentry id="folders-properties-mailinglist-help"> + <term> + <guilabel>List Help</guilabel> + </term> + <listitem> + <para> + This address is used for requesting help for this + mailing list. This is usually an email address. + </para> + </listitem> + </varlistentry> + </variablelist> + +<para>After selecting the appropriate <guilabel>Address type</guilabel> you +enter the email address or the address of the webpage and then click on +<guilabel>Add</guilabel>. With <guilabel>Remove</guilabel> you can remove +addresses.</para> + +<para>If all addresses have been added then you can execute an action, ⪚ +go to the list archives, by selecting the appropriate +<guilabel>Address type</guilabel> and then clicking on +<guilabel>Invoke Handler</guilabel>. If there is an email address and an +address of a webpage for the desired action then you will have to select +the <guilabel>Preferred handler</guilabel> prior to clicking on +<guilabel>Invoke Handler</guilabel>. Select <guilabel>KMail;</guilabel> if you +want to send a message to the email address and select +<guilabel>Browser</guilabel> if you want to go to the webpage.</para> + +<para>Alternatively to invoking the handler for +<guilabel>Post to List</guilabel> you can send a new message to the +mailing list via <menuchoice><guimenu>Message</guimenu><guimenuitem>New +Message to Mailing-List...</guimenuitem></menuchoice> or by clicking with +the <mousebutton>middle</mousebutton> mousebutton on the folder in the folder +list.</para> + +</sect3> + + <sect3 id="folders-properties-acl"> + <title>Access Control tab (&imap; only)</title> + + <para> + Here you can manage the access control lists (&acl;s) of + &imap; folders. + </para> + + <para> + The currently active &acl; is shown in the list. It consists + of pairs of <guilabel>User Id</guilabel>s and the + <guilabel>Permissions</guilabel> granted to users identified + by that <guilabel>User Id</guilabel>. + <footnote> + <para> + Note that a single <guilabel>User Id</guilabel> might + refer to more than one user. Depending on the &imap; + server and its configuration, there may be User Ids + that correspond to groups of users, anonymous users, or + any user. Consult the manual of your specific &imap; + server implementation for more information. + </para> + </footnote> + &acl;s are settable per-folder. + </para> + + <note> + <para> + As with everything else when using <emphasis>disconnected + &imap;</emphasis>, you need to sync with the server for + the changes to be transferred to the server. + </para> + </note> + + <para> + &imap; &acl;s define a lot of fine-grained permissions that + you can grant or deny other users. For the sake of clarity, + &kmail; will present them as the following five categories + that you can choose from (see <xref + linkend="table-acl-summary"/> for the details if you already + know &imap; &acl;s). + </para> + + <variablelist> + + <varlistentry id="folders-properties-acl-none"> + <term> + <guilabel>None</guilabel> + </term> + <listitem> + <para> + Grants the users identified by <guilabel>User + Id</guilabel> no rights at all. This is also the + default for users not explicitly (or implicitly, as a + group) listed in the &acl;. These users will not see + this folder in the list of &imap; folders presented to + them by their mail clients. + </para> + </listitem> + </varlistentry> + + <varlistentry id="folders-properties-acl-read"> + <term> + <guilabel>Read</guilabel> + </term> + <listitem> + <para> + Grants the users identified by <guilabel>User + Id</guilabel> reading rights for this folder. This + also includes the ability for their mail clients to + mark mails as read and store this information on the + server.<!-- --><footnote> + <para> + Every user has its own list of read mail, so none + of your unread mails will suddenly be marked as + read just because someone else has already read them. + </para> + </footnote> + </para> + <para> + These users will see this folder in the list of &imap; + folders presented to them by their mail clients. + </para> + <para> + Use this to create a shared folder that others can + read, but not modify. + </para> + <informalexample> + <para> + If you were the editor of a company's news letter, + you could create a folder for the purpose of + distributing the news letter, grant everyone reading + rights, and save the letter to this folder instead + of sending it out by email to a catch-all address. + </para> + </informalexample> + </listitem> + </varlistentry> + + <varlistentry id="folders-properties-acl-append"> + <term> + <guilabel>Append</guilabel> + </term> + <listitem> + <para> + (also known as <guilabel>Post</guilabel>) + </para> + <para> + Grants the users identified by <guilabel>User + Id</guilabel> reading (see above) and posting rights + for this folder. + </para> + <para> + Use this to create a shared folder that others can + read and post messages to, but can not otherwise + modify. + </para> + <informalexample> + <para> + If you wanted to create a company-wide discussion + forum, instead of using a web-based form or a + separate company-private usenet server, you could + create a bunch of folders (one per topic), and grant + everyone reading and posting rights. Instead of + posting to an &nntp; server or writing their + messages into a web form, people would just write + emails and store them in the folder suiting the + topic of the message. + </para> + </informalexample> + </listitem> + </varlistentry> + + <varlistentry id="folders-properties-acl-write"> + <term> + <guilabel>Write</guilabel> + </term> + <listitem> + <para> + Grants the users identified by <guilabel>User + Id</guilabel> reading, posting (see above), and + writing rights for this folder. + </para> + <para> + The right to write to a folder includes deleting of + messages, creating subfolders, and storing other + attributes than read/unread on the server (⪚ + answered). + </para> + <para> + Use this to create a shared folder that everyone has + (almost, see <xref linkend="folders-properties-acl-all"/>) + the same rights for. + </para> + <informalexample> + <para> + In the <xref + linkend="folders-properties-acl-append"/> example, + you could assign write rights to a group of people + acting as moderators, which would then be able to + remove off-topic posts, and create sub-topic-folders + for high-traffic folders. + </para> + </informalexample> + </listitem> + </varlistentry> + + <varlistentry id="folders-properties-acl-all"> + <term> + <guilabel>All</guilabel> + </term> + <listitem> + <para> + Grants the users identified by <guilabel>User + Id</guilabel> reading, posting, writing (see above), + as well as administration rights, &ie; the right to + modify the &acl; of this folder. + </para> + <para> + This is the default set of rights for the owner of a + folder. + </para> + </listitem> + </varlistentry> + + </variablelist> + + <para> + <xref linkend="table-acl-summary"/> summarizes the &imap; + &acl; rights associated with each permission level. + </para> + + <table id="table-acl-summary"> + <title> + &acl; Rights Summary + </title> + <tgroup cols="6"> + <thead> + <row> + <entry>&acl; right</entry> + <entry><xref linkend="folders-properties-acl-none"/></entry> + <entry><xref linkend="folders-properties-acl-read"/></entry> + <entry><xref linkend="folders-properties-acl-append"/></entry> + <entry><xref linkend="folders-properties-acl-write"/></entry> + <entry><xref linkend="folders-properties-acl-all"/></entry> + </row> + </thead> + <!--tfoot/--> + <tbody> + <row> + <entry>Lookup</entry> + <entry></entry> + <entry>x</entry> + <entry>x</entry> + <entry>x</entry> + <entry>x</entry> + </row> + <row> + <entry>Read</entry> + <entry></entry> + <entry>x</entry> + <entry>x</entry> + <entry>x</entry> + <entry>x</entry> + </row> + <row> + <entry>Store Seen</entry> + <entry></entry> + <entry>x</entry> + <entry>x</entry> + <entry>x</entry> + <entry>x</entry> + </row> + <row> + <entry>Insert</entry> + <entry></entry> + <entry></entry> + <entry>x</entry> + <entry>x</entry> + <entry>x</entry> + </row> + <row> + <entry>Post</entry> + <entry></entry> + <entry></entry> + <entry>x</entry> + <entry>x</entry> + <entry>x</entry> + </row> + <row> + <entry>Write Flags</entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>x</entry> + <entry>x</entry> + </row> + <row> + <entry>Create</entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>x</entry> + <entry>x</entry> + </row> + <row> + <entry>Delete</entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>x</entry> + <entry>x</entry> + </row> + <row> + <entry>Administer</entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry>x</entry> + </row> + </tbody> + </tgroup> + </table> + + </sect3> + +</sect2> + +<sect2 id="folders-format"> +<title>Folder Format</title> + +<para>A message folder can be either in <guilabel>mbox</guilabel> or in <guilabel>maildir</guilabel> +format. <guilabel>mbox</guilabel> saves all messages of a folder to one file, +whereas <guilabel>maildir</guilabel> saves each message to its own file. +<guilabel>maildir</guilabel>, which is the default format, can be considered more +robust, but it can be slower on some file systems. If you are unsure, +choose <guilabel>maildir</guilabel>.</para> + +<para>Note that there is currently no feature in &kmail; that allows you to convert +between both formats automatically, but you can just move all messages from an old +<guilabel>mbox</guilabel> folder to a new <guilabel>maildir</guilabel> folder or +vice-versa.</para> + +</sect2> + +</sect1> + +<sect1 id="filters"> +<title>Message Filters</title> +<anchor id="filters-id"/> + +<para>After using &kmail; for a while, you may find that you have trouble +sorting out the new messages in your inbox when they arrive. Filters allow you +to automatically perform certain actions on incoming messages and to manually +perform actions on selected messages in a folder.</para> + +<para>Please note that the filters described in this section are +applied <emphasis>after</emphasis> the messages have been downloaded +from your account -- if you want to filter messages on the server, see +<link linkend="popfilters">Download Filters</link>.</para> + +<para>Filters consist of: filter criteria, whose rules are used as +criteria to determine whether this filter should be applied to a given +message; and a list of filter actions, which describe what is to be +done with, or to, the message if the search pattern matches. Read more +about filter criteria and filter actions in the following +subsections.</para> + +<note><para>Filters are considered one after the other, +starting with the first filter in the list. The first one whose +pattern matches the given message gets executed; you can request that +the remaining filters also be applied, but the default is to stop +processing at the first matching filter. </para></note> + +<para>Usually, filters are used on incoming messages, but they can +also be applied to sent messages or to an arbitrary message or group +of messages. To selectively filter messages, select the messages you +want to filter in the message list and either type <keycombo +action="simul">&Ctrl;<keycap>J</keycap> </keycombo> or select +<menuchoice><guimenu>Message</guimenu> <guimenuitem>Apply +Filters</guimenuitem></menuchoice>: this will apply all filters that +have been marked for manual filtering in the <link +linkend="filter-dialog">filter dialog</link> to those messages.</para> + +<sect2 id="filter-quick"> +<title>Fast Filter Creation</title> + +<para>There are two methods for creating a filter; the quick method is +to use <menuchoice><guimenu>Message</guimenu><guimenuitem>Create +Filter</guimenuitem></menuchoice>: this will call the filter dialog +and present you with a new filter which has the first rule of the +search pattern and the first action (as <guilabel>Move into Folder</guilabel>) +preset. In most cases, all you have to do is select the folder where the message +should be moved to; but you can, of course, edit the filter as you +like.</para> + +<para>When creating a filter on mailing list messages this method +will try really hard to find a criterion that +uniquely identifies messages from that list; If it succeeds, the guessed +name of the list is presented in the +<menuchoice><guimenu>Message</guimenu><guisubmenu>Create +Filter</guisubmenu><guimenuitem>Filter on +Mailing-List...</guimenuitem></menuchoice> menu entry.</para> + +<para>The second method is to manually construct a filter from scratch +by calling the filter dialog through +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Filters...</guimenuitem></menuchoice>. The filter dialog is described in +detail in the following subsection.</para> +</sect2> + +<sect2 id="filter-dialog"> +<title>The Filter Dialog</title> +<anchor id="filter-dialog-id"/> + +<para>This dialog allows you to manage and edit your list of +filters.</para> + +<para>You can reach it either via +<menuchoice><guimenu>Message</guimenu><guisubmenu>Create +Filter</guisubmenu></menuchoice> or +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Filters...</guimenuitem></menuchoice>.</para> + +<para>The dialog is divided into four main sections:</para> +<variablelist> +<varlistentry> +<term><guilabel>Available Filters</guilabel></term> +<listitem><para>This group contains the list of filters and some action +buttons to modify the filters, namely: to create new filters; to move them up or +down the list; to delete them; or to rename them. If you select +a filter from the list, its properties are shown in the right-hand half +of the dialog.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Filter Criteria</guilabel></term> <listitem><para>In +this group you can edit the pattern that messages must match for the +filter to be applied to them. You can select here whether all of the +defined rules must match or whether it suffices that any one of them +matches. See <link linkend="filter-criteria">Search Patterns</link> +below for a detailed description of each search rule type.</para> + +<para> You can click on <guibutton>More</guibutton> to get an +additional (initially empty) rule if you want to define more-complex +patterns and on <guibutton>Fewer</guibutton> to remove the last +rule. <guibutton>Clear</guibutton> clears the pattern, &ie; it removes +all but two rules from screen and resets those two.</para> +<para>Invalid or empty rules are not evaluated.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Filter Actions</guilabel></term> <listitem><para>In +this group you can edit the list of actions that are applied to all +messages that match the defined filter criteria. See <link +linkend="filter-action">Filter Actions</link> below for a detailed +description of each action type.</para> + +<para> You can click on <guibutton>More</guibutton> to get a new, +empty action (if you want to define more than one action) and on +<guibutton>Fewer</guibutton> to remove the last +action. <guibutton>Clear</guibutton> clears the list, &ie; it +removes all but one action and resets that one.</para> +<para>Invalid or empty actions are not executed.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Advanced Options</guilabel></term> + +<listitem> + +<para>In this group you can define a few advanced options for filters +that allow you to refine your filtering.</para> + +<para>Using the first row of check boxes, you can toggle when the +filter is applied: the <guilabel>to incoming messages</guilabel> +option means that the filter is applied to messages when you receive +them (&ie; on <guiicon>Check Mail</guiicon>); the <guilabel>to sent +messages</guilabel> options means that the filter is applied to +messages when you send them and the <guilabel>on manual +filtering</guilabel> option controls whether to apply this filter when +filtering is specifically selected (&ie; via +<menuchoice><guimenu>Message</guimenu> <guimenuitem>Apply +Filters</guimenuitem></menuchoice>.)</para> + +<para>The <guilabel>If this filter matches, stop processing here</guilabel> +check box in the second row controls whether or not the filters after +the current filter will be applied, if the current filter matches.</para> + +<para>If the <guilabel>Add this filter to the Apply Filter menu</guilabel> +check box in the third row is selected, this filter will be inserted +in the <menuchoice><guimenu>Message</guimenu> <guimenuitem>Apply +Filter</guimenuitem></menuchoice> submenu. You can then apply this +filter to a message. Another way of applying filters is to use +<menuchoice><guimenu>Message</guimenu> <guimenuitem>Apply +Filters</guimenuitem></menuchoice> menu option, which applies <emphasis>all</emphasis> +the filters - one after another until they are all used or one of the +filters that matches has the <guilabel>If the filters matches, stop +processing here</guilabel>.</para> + +</listitem> +</varlistentry> +</variablelist> + +<note><para>Filters are automatically named unless you explicitly +rename them using the <guibutton>Rename...</guibutton> button. +The dialog assumes that it should continue auto-naming the filter +as long as the filter name starts with <quote><</quote>. +</para></note> + +<note> +<para>If you apply filter changes, via +<guibutton>OK</guibutton> or <guibutton>Apply</guibutton>, only valid +filters are actually copied to the internal filter manager.</para> + +<para>Similarly, empty rules and actions are removed from the pattern +and action list respectively, before the filter is saved.</para> +</note> + +</sect2> + +<sect2 id="filter-criteria"> +<title>Search Patterns</title> + +<para>The most common use of filters is to filter on the sender of +messages; this can be done by choosing <guilabel>From</guilabel>. A +good bet for a mailing list would be +<guilabel><recipients></guilabel>, but there are other criteria +a filter can search for (note that all patterns are interpreted +case-insensitively):</para> + +<variablelist> +<varlistentry> +<term><guilabel><message></guilabel></term> +<listitem> +<para>Searches the whole message (&ie; headers, body and attachments, +if any);</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel><body></guilabel></term> +<listitem> +<para>Searches the body of the message (&ie; the whole message except the headers);</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel><any header></guilabel></term> +<listitem> +<para>Searches the headers of the message;</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel><recipients></guilabel></term> +<listitem> +<para>Searches the <quote>To</quote> and <quote>CC</quote> header fields of the message;</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel><size in bytes></guilabel></term> +<listitem> +<para>Sets upper or lower bounds on the message size;</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel><age in days></guilabel></term> +<listitem> +<para>Sets upper or lower bounds on the message age;</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel><status></guilabel></term> +<listitem> +<para>Sets restrictions on the status of the message;</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Any other name</term> +<listitem> +<para>Searches the header field that is given by that name.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>The list of possible rules depends on what you selected in the first +drop down box. The available rules are:</para> + +<informaltable> +<tgroup cols="3"> +<thead> +<row> +<entry>Rule</entry> +<entry>Available for</entry> +<entry>Description</entry> +</row> +</thead> +<tbody> +<row> +<entry><guilabel>contains</guilabel>/<guilabel>does not contain</guilabel></entry> +<entry>all textual search items</entry> +<entry>Matches if the searched item contains (or does not contain) the given +text.</entry> +</row> +<row> +<entry><guilabel>equals</guilabel>/<guilabel>does not equal</guilabel></entry> +<entry>most textual search items</entry> +<entry>Matches if the searched item is equal to (or not equal to) the given +text.</entry> +</row> +<row> +<entry><guilabel>matches regular expr.</guilabel>/<guilabel>does not match reg. expr.</guilabel></entry> +<entry>all textual search items</entry> +<entry>Matches if a part of the searched item matches the given regular +expression (or does not match it). If the regular expression editor is +installed then you can edit the regular expression by clicking on the <guilabel>Edit...</guilabel> button.</entry> +</row> +<row> +<entry><guilabel>has an attachment</guilabel>/<guilabel>has no attachment</guilabel></entry> +<entry><guilabel><message></guilabel></entry> +<entry>Matches if the message has an attachment (or does not have an attachment).</entry> +</row> +<row> +<entry><guilabel>is in address book</guilabel>/<guilabel>is not in address book</guilabel></entry> +<entry>most textual search items</entry> +<entry>Matches if the searched item contains an address that is in your address +book (or if the searched items contains only unknown addresses). Of course, +this rule makes only sense for address fields like From or +<guilabel><recipients></guilabel></entry> +</row> +<row> +<entry><guilabel>is in category</guilabel>/<guilabel>is not in category</guilabel></entry> +<entry>most textual search items</entry> +<entry>Matches if the searched item contains an address that is in the +specified category in your address book (or if the searched item contains +no address that is in the specified category). Again, this rule makes only +sense for address fields.</entry> +</row> +<row> +<entry><guilabel>is equal to</guilabel>/<guilabel>is not equal to</guilabel></entry> +<entry>numerical search items</entry> +<entry>Matches if the value of the search item is equal to (or not equal to) +the specified value.</entry> +</row> +<row> +<entry><guilabel>is less than</guilabel></entry> +<entry>numerical search items</entry> +<entry>Matches if the value of the search item is less than +the specified value.</entry> +</row> +<row> +<entry><guilabel>is greater than</guilabel></entry> +<entry>numerical search items</entry> +<entry>Matches if the value of the search item is greater than +the specified value.</entry> +</row> +<row> +<entry><guilabel>is less than or equal to</guilabel></entry> +<entry>numerical search items</entry> +<entry>Matches if the value of the search item is less than or equal to +the specified value.</entry> +</row> +<row> +<entry><guilabel>is greater than or equal to</guilabel></entry> +<entry>numerical search items</entry> +<entry>Matches if the value of the search item is greater than or equal to +the specified value.</entry> +</row> +<row> +<entry><guilabel>is</guilabel>/<guilabel>is not</guilabel></entry> +<entry><guilabel><status></guilabel></entry> +<entry>Matches if the message has (or does not have) the specified status.</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +</sect2> + +<sect2 id="filter-action"> +<title>Filter Action</title> + +<para>The most common use of filters is to sort incoming messages to +certain folders; this can be done by choosing <guilabel>Move into +Folder</guilabel>. Here is a list of all possible actions:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Move into Folder</guilabel></term> +<listitem> +<para>This will file the message into another folder, removing it from +its current folder if necessary; you cannot, currently +use &imap; folders as a target.</para> +<!-- fixme: still correct? --> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Copy to Folder</guilabel></term> +<listitem> +<para>This will copy the message to another folder.</para> +<note><para>You currently cannot use &imap; +folders as a target.</para></note> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Set Identity To</guilabel></term> +<listitem> +<para>This will set the identity that will be used if you reply to this +message.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Mark As</guilabel></term> +<listitem> +<para>This allows you to mark the message as read or important (flagged), but +also as forwarded, replied, &etc;</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Send Fake MDN</guilabel></term> +<listitem> +<para>This will send a faked message disposition notification (&ie; a read +receipt) to the sender of the message.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Set Transport To</guilabel></term> +<listitem> +<para>This will set the method of transport (⪚ <acronym>SMTP</acronym>) +that will be used if you reply to the message.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Set Reply-To To</guilabel></term> +<listitem><para>This will modify the <guilabel>Reply-To</guilabel> field of this +message. This can be useful for mailing lists that automatically set a Reply-To +which you do not like.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Forward To</guilabel></term> +<listitem><para>This will forward the message inline (&ie; as if you selected <menuchoice><guimenu>Message</guimenu><guimenuitem>Forward</guimenuitem><guimenuitem>Inline...</guimenuitem></menuchoice>) to another email address.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Redirect To</guilabel></term> +<listitem><para>This will redirect the message as-is to another email address.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Confirm Delivery</guilabel></term> +<listitem><para>Will try to return a message to the sender that +indicates successful delivery of their message, if the sender requested that.</para> <para>This +action allows you to select who will get delivery receipts from +you. <!-- FIXME: removed-->Though you can globally enable the sending of delivery +confirmations in the <guilabel>Configure &kmail;...</guilabel> dialog +(<link linkend="configure-security"><guilabel>Security</guilabel> +page</link>) we recommended not to send them to everyone, since this +makes tracking of spam messages, for example, very easy for the sender.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Execute Command</guilabel></term> +<listitem> +<para>This will execute a program, but will not modify the +message. Specify the full path to the program you want to +execute; &kmail; will then block until the program returns. +If you do not want &kmail; to block then append '&' to the command. +You can feed +the program with the parts of the mail: <symbol>%0</symbol>, +<symbol>%1</symbol>, &etc; stand for files representing +the message parts; for common messages <symbol>%0</symbol> is the +text, <symbol>%1</symbol> the first attachment and so +on. Additionally, the whole message is fed into the program's +<acronym>stdin</acronym>; and every occurrence of +<symbol>%{foo}</symbol> is replaced by the content of the foo +header.</para> + +<!-- fixme: still correct? --> +<warning><para>This currently only works if the message has +<emphasis>at least one</emphasis> attachment. No, not even +<symbol>%0</symbol> will work in the general +case!</para></warning> + +<tip><para> You can enter arbitrarily-complex shell commands here, +since &kmail; uses a sub shell to execute the command line; therefore, +even this command will work (within its limits): +<userinput><command>uudecode</command> <option>-o</option> +<parameter>$(mktemp kmail-uudecoded.XXXXXX)</parameter> && +<command>echo</command> <parameter>$'\a'</parameter></userinput></para></tip> +<!-- fixme: is this uudecode tip useless now?? --> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Pipe Through</guilabel></term> +<listitem> +<para>This will feed the message to a program: if the program returns +output, the entire message (including the headers) will be replaced +with this output; if the program does not return output or exits +with a return code other than 0 (indicating an error occurred), the message +will not change. Specify the full path to the program. The same +substitutions (<symbol>%n</symbol>, +<symbol>%{foo}</symbol> as with <guilabel>execute +command</guilabel> are performed on the command line.</para> +<warning><para>Be cautious with this action, as it will easily mess up +your messages if the filter program returns garbage or extra +lines.</para></warning> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Remove Header</guilabel></term> +<listitem> +<para>Will remove all header fields with the +given name from the message. This is useful mainly for removing bogus +<quote>Reply-To:</quote> headers.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Add Header</guilabel></term> +<listitem> +<para>If no such field is already present this will add a new header field +with the given name and value to the message; if there already is a +header field with that name, it is overwritten with the +given value; if there are already multiple headers with the given +name (⪚ <quote>Received:</quote> headers), an arbitrary one of them is +overwritten and the others are left unchanged -- this is a known +limitation. You may want to combine this filter with the +<guilabel>remove header</guilabel> filter above to make sure that +there are no other headers with that name in the message.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Rewrite Header</guilabel></term> +<listitem> +<para>Will scan the given header field, modify its contents and write +it back. The search string is always interpreted as a case-sensitive +regular expression. The replacement string is inserted literally +except for occurrences of <userinput>\n</userinput>, +<userinput>$n</userinput> and <userinput>${nn}</userinput>, where +<userinput>n</userinput> is a positive (single-digit, except for the +third form) number or <userinput>0</userinput>. These constructs are +interpreted as back references to substrings captured with parentheses +in the search string.</para><para>Analogous restrictions as in the +<guilabel>add header</guilabel> action apply here, too.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Play Sound</guilabel></term> +<listitem> +<para>Will play the specified sound.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="filter-examples"> +<title>Filter Examples</title> + +<para>If I am subscribed to the (general) &kde; List, I could create a +folder for the list (I will call it +<replaceable>KDE-General</replaceable>) and use a filter to +automatically transfer new messages from my inbox to my +<replaceable>KDE-General</replaceable> folder if they are from the +&kde; List. Here is how to create this filter:</para> + +<procedure> +<title>Filtering a mailing list</title> +<step> +<para>Try if <menuchoice><guimenu>Message</guimenu><guisubmenu>Create +filter</guisubmenu><guimenuitem>Filter on +Mailing-List...</guimenuitem></menuchoice> can identify the mailing +list (the name of the list should then appear in the menu item); in +this case, this works and I am presented a filter that has +<quote>List-Id<guilabel>contains</guilabel> +<kde.kde.org></quote> preset. You select the +desired destination folder from the folder pull-down menu in the +<guilabel>Filter Action</guilabel> group and that is it.</para> + +<para>If that does not work, think of a unique way of identifying the +messages you want to filter. The (almost) unique property of my &kde; +List messages is that they always contain +<quote>kde@kde.org</quote> in the +<guilabel>To:</guilabel> or <guilabel>CC:</guilabel> field. It is only +almost unique, because this fails for cross-posted messages.</para> +</step> +<step> +<para>Select <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Filters...</guimenuitem></menuchoice>.</para> +</step> +<step> +<para>Press the <guibutton>New</guibutton> button to create an empty +filter. It will appear as <guilabel><unknown></guilabel>.</para> +</step> +<step> +<para>In the <guilabel> Filter Criteria</guilabel> area, select +<guilabel><recipients></guilabel> from the first drop-down box, +<guilabel>contains</guilabel> from the second drop-down box, and type +<userinput>kde@kde.org</userinput> in the text +field.</para> +</step> +<step> +<para>Skip down to the <guilabel>Filter Actions</guilabel> section. Select <guilabel>file into +folder</guilabel> from the first drop-down box. A new drop-down box +containing a list of folders will appear. Select the folder that you +want the filtered messages to be transferred to. For this example, you would select +<guilabel>KDE-General</guilabel> from the drop-down box.</para> +</step> +</procedure> + +<para>You may find that you need to use more powerful criteria to +properly filter your messages; for example, you may only want to +filter the &kde; List messages that are written by your friend <replaceable>Fred +Johnson <fj@anywhere.com></replaceable>. This is where the rest of the +matching criteria section comes into play:</para> + +<procedure> +<title>Extending the filter</title> +<step> +<para>Open up the <guilabel>Configure Filters...</guilabel> window and select +the filter you just created.</para> +</step> +<step> +<para>Since you want to filter all messages that have +<replaceable>kde@kde.org</replaceable> in the +<guilabel>To:</guilabel> or <guilabel>CC:</guilabel> field +<emphasis>and</emphasis> that are from Fred, check the +<guibutton>Match all of the following</guibutton> radio +button.</para> +</step> +<step> +<para>Now, go to the second search rule and select the following from +the pull-down menus: <guilabel>From</guilabel>, +<guilabel>contains</guilabel>. Now, type +<userinput>fj@anywhere.com</userinput> in the text field.</para> +</step> +</procedure> + +<para>You now have a filter that transfers all &kde; List messages +that are from <userinput>fj@anywhere.com</userinput>.</para> +<!-- fixme: trigger with ctrl-j or whenever new mail arrives (unless +<guilabel>Advanced Options</guilabel> are changed. --> +</sect2> + +<sect2 id="filter-optimization"> +<title>Filter Optimization</title> + +<para>It is important to know that, for example, the order of the +filters has an impact on the speed of the filter process. Here are +some ideas which can help you to improve the filtering: +</para> + +<variablelist> +<varlistentry> +<term>Stop filter processing as early as possible:</term> +<listitem> +<para>If you know that a filter finally processes a certain class of +messages, please make sure to check the option <guilabel>If this filter +matches, stop processing here</guilabel> for the filter. +This will avoid the evaluation of the filter rules of all subsequent +filters. (See the advanced options in the <link linkend="filter-dialog-id"> +Filter Dialog</link>).</para> +<para>An example is filtering messages from mailing lists via List-Id +header into separate folders. Having found out that a message came from +list A means that you can avoid checking the next filter for messages +from list B. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Consider the costs of the evaluation of filter rules:</term> +<listitem> +<para>The time required to evaluate a filter rule depends on the way +the rule is constructed. In particular, scanning for a +substring using the <guilabel>contains</guilabel> operation is faster +than a pattern matching using the <guilabel>matches regular +expr.</guilabel> operation. +</para> +<para>Another dependency is on the amount of data which is used for the +evaluation of a filter rule. If the rule is based on a message header, +its evaluation should normally be much faster than the evaluation of +a rule based on the complete message. +</para> +<para>You should try to keep the filter rules as simple as possible. +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>Check the order of your filters:</term> +<listitem> +<para>All the different filter actions have a different complexity. +The most expensive filter actions are <guilabel>pipe through</guilabel> +and <guilabel>execute command</guilabel>, because both need external +programs to be run. Placing filters containing these filter actions +behind other filters that can reduce the number of times these complex +actions are required is useful, if the filter logic does allow +this.</para> +<para>An example is filtering messages from a mailing list and detecting +spam messages. For the spam detection you will usually use an external +tool via a <guilabel>pipe through</guilabel> action. Filtering the messages +for the mailing list is done via the List-Id header. If you do not want to +check the messages from the mailing list for spam too, it is better to +use the filter for the mailing list messages before the filter for the +spam detection. This way you avoid the expensive and slow spam check for all +messages which were identified as mailing list messages. +</para> +</listitem> +</varlistentry> +</variablelist> +</sect2> + +<sect2 id="filter-logging"> +<title>Filter Log</title> +<para>If you want to verify that your filters work as intended, you can +open a viewer for the filter log via <menuchoice><guimenu>Tools</guimenu> +<guimenuitem>Filter Log Viewer...</guimenuitem></menuchoice>. +</para> +<para>In the viewer, there you can configure the logging of the filter +processing. You can control the detail level of the log, clear the log +or save the log into a file. The log can provide valuable information if +you need to debug your filtering process. +</para> +</sect2> +</sect1> + +<!-- dnaber update 2004-02-22 --> +<sect1 id="popfilters"> +<title>Download Filters</title> + +<para>Download Filters can be used to filter mail from a POP server, +<emphasis>before</emphasis> they are completely downloaded; you can use them +to prevent &kmail; from downloading huge messages and save time this +way.</para> + +<para>In the configuration dialog of the POP account you can enable +download filtering by checking the <guilabel>Filter messages if +they are greater than</guilabel> box; once you have done that, you can specify a size +which is used as a threshold: messages exceeding this size will be +checked against the filter rules you defined -- if no filter rule +matches, they will be shown in a confirmation dialog and you can +decide what to do with them. The default size for filtering is 50,000 +Bytes; this is a good value as the overhead is kept to a minimum -- +every message that is looked at by the filter causes additional +traffic because the header of the message is downloaded twice. The +default action is <guilabel>Download mail</guilabel> to prevent the +loss of messages.</para> + +<warning><para>Be careful with the <guilabel>Delete mail from +server</guilabel> option since once a mail is deleted on the server +there is no way to get it back.</para></warning> + +<para>With a really good set of filter rules, it is possible that all +messages that exceed the threshold size are automatically tagged +(&ie; downloaded, kept on the server or deleted) and you would never +be bugged by the confirmation dialog. Be careful though, since once a +message is matched by a filter rule, you have no guarantee that you +can change the action before it is executed: the confirmation dialog will +be displayed <emphasis>only</emphasis> if there is a message left that +was not matched by a filter rule.</para> + +<sect2 id="popfilters-dialog"> +<title>The <guilabel>Configure Pop Filter</guilabel> Dialog</title> + +<para>Adding filter rules works similar as for <link +linkend="filters">message filters</link>. On the left hand side you +can manage the existing filters. Use the <guiicon>New</guiicon> +button to add a filter. On the right hand side you can configure +under which conditions the current filter should match. Using <guilabel>Filter +Action</guilabel> you specify what will happen to a message that is +matched by this rule. The available options are:</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Download mail</guilabel></term> +<listitem> +<para>Will download the messages matched by the filter, just as any other message +that does not exceed the threshold size.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Download mail later</guilabel></term> +<listitem> +<para>Will tag the messages for later download. This means the messages matched +will stay on the POP server until you choose to download them by +changing the action manually.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Delete mail from server</guilabel></term> +<listitem> +<para>Will delete the message from the server and does not download it. Once you +deleted a message from the server, there is <emphasis>no</emphasis> way you can undo this. +Be careful, as rules could match messages you actually want, too.</para></listitem> +</varlistentry> + +</variablelist> + +<para>The option <guilabel>Always show matched 'Download Later' messages in +confirmation dialog</guilabel> will cause the confirmation dialog to +show up during mailbox check if at least one message was tagged for +<guilabel>Download Later</guilabel> - even if all messages exceeding +the threshold size were matched by a rule. This option is useful in the +case you have messages matched by a rule and tagged for +<guilabel>Download Later</guilabel>, but you do not get any message +exceeding the size limit for a very long time. Without this option, +the confirmation dialog would never show up and you would never have +a chance to get the queued message by changing the action manually.</para> + +</sect2> + +<sect2 id="popfilters-confirmation"> +<title>The Confirmation Dialog</title> + +<para>This dialog shows up whenever you have POP filtering switched +on and messages were found on the server that exceed the threshold +size you defined for the POP account. Now you have the chance to +decide what you want to do with that message. The options are +<guilabel>Download</guilabel> (green), <guilabel>Download +later</guilabel> (yellow with egg watch) and <guilabel>Delete from +server</guilabel> (red <quote>X</quote>). Be cautious with the delete +option, since once you deleted a mail from the server, there is no +way to undelete it again.</para> + +<para>In the <guilabel>Filtered Messages</guilabel> section you can +check the box if you receive messages that were automatically tagged for +a certain action (download, download later, delete) by a filter rule. +The checkbox is only enabled if you receive some messages that were +matched by a filter rule; once you check it, a list similar to the +one for the not-automatically-tagged messages will be displayed and you +can change the action for every single message.</para> + +<para>Please note that if there is a message exceeding the size +limit, but all messages are matched by a filter rule the dialog will +not be displayed. One exception occurs if you have checked +<guilabel>Always show matched 'Download Later' messages</guilabel> in +the <guilabel>Global Options</guilabel> section of the POP filter +configuration dialog; then, the dialog will also be displayed if you only +have matched messages, but at least one message was tagged for +<guilabel>Download later</guilabel>.</para> + +</sect2> + +</sect1> + +<sect1 id="multiple-accounts"> +<title>Using Multiple Accounts</title> + +<para>Multiple accounts are used to check for messages from more than one email address +and/or mail server. Select <menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Configure &kmail;...</guimenuitem></menuchoice> and click on the +<guilabel>Network</guilabel> page to add or change your account settings. See the +<link linkend="getting-started">Getting started</link> section for more +information on the settings in the <guilabel>Network</guilabel> page.</para> + +<para>To check for messages from a particular account, use the +<menuchoice><guimenu>File</guimenu><guimenuitem>Check Mail +In</guimenuitem></menuchoice> submenu to select the account to check +for mail. You can also press the mouse button on the <guiicon>Check +Mail</guiicon> icon for some time to get a list of accounts.</para> + +</sect1> + +<sect1 id="pgp"> +<!-- This section is from Andreas Gungl, 2000-05-21, updated 2002-10-06 by Ingo Kloecker --> +<title>Signing and Encrypting Messages with <application>PGP</application> +or <application>GnuPG</application></title> + +<note><para>There have been major changes in the way &kmail; handles +signing/encryption. The following introduction applies to the previous +version of &kmail;. You can still read the introduction to get an overview +about how to sign/encrypt messages, but the details, especially those of +the configuration, will differ.</para></note> + +<para>This is a short introduction on how to setup &kmail;'s +<application>PGP</application> (<application>Pretty Good Privacy</application>) support; +it gives some hints on the use of +<application>PGP</application> too. It is written for people who are beginners in +this area; if you are familiar with the use of <application>PGP</application>, you can +skip most of the steps. This documentation, and the &kmail; user interface, +generally talk only about <quote>PGP</quote>, but it applies to +both <application>PGP</application> and <application>GnuPG</application> +(<application>GNU Privacy Guard</application>), +(although some <application>GnuPG</application> command-line parameters +may be different.)</para> + +<para>Please +also check out the <link linkend="pgp-faq">&FAQ; item about +<application>PGP</application></link>.</para> + +<warning><para>Attachments will not be signed/encrypted if you are using +inline OpenPGP: to sign/encrypt attachments, you have to install GnuPG and +some necessary libraries; +then, you can decide for each attachment whether it should be signed/encrypted or not. +</para></warning> + +<warning><para>&kmail; has to rely on <application>PGP</application>'s +output; this output is often different between different versions of +<application>PGP</application>, so it is important that you test if encryption +really works with your setup before you start using it seriously. &kmail; might +<emphasis>not</emphasis> warn you if something fails -- enable +<guilabel>Show signed/encrypted text +after composing</guilabel>. </para></warning> + +<para>To setup and use <application>PGP</application> support in &kmail; it is +necessary to have <application>PGP</application> installed and set up +properly; of course, we cannot give you a full introduction of +<application>PGP</application> here. We will only mention the steps you have to +do to get <application>PGP</application> going. For details you should have a look at +the excellent <application>PGP</application> documentation +or <ulink url="http://www.gnupg.org/docs.html#guides">The GNU Privacy Handbook</ulink>.</para> + +<para>It is certainly a good idea to study this documentation as well as an +introduction into public key cryptography (⪚ out of the +<application>PGP</application> 6.5.x package): there you can learn a lot about +the basic concepts, which will help you to understand what is going on; also, +many security related issues you should know about are discussed there.</para> + +<para>Now, let us start.</para> + +<sect2 id="pgp-preconditions"> +<title>Preconditions</title> + +<para>&kmail; expects that your <application>PGP</application> binary is called +<command>pgp</command>; in the case of <application>GnuPG</application>, it expects +the binary to be called <command>gpg</command>. If this is not the case for you, +just make a symlink.</para> + +<para>If you have not done so, you have to generate a key pair (secret and public +key) for your identity. You must do this at the command line: use +<userinput><command>pgp</command> <option>-kg</option></userinput> +or <userinput><command>gpg</command> <option>--gen-key</option></userinput>: &kmail; +has no internal support for <application>pgp</application>'s key generation at +this time. The identity (normally your name followed by your email address +within brackets, such as <userinput>John Doe +<john@example.com></userinput>) and your passphrase are important for the +co-operation between &kmail; and <application>PGP</application>.</para> + +</sect2> + +<sect2 id="pgp-settings"> +<title><application>PGP</application>-Related Settings in &kmail;</title> + +<para>Select the <guilabel>OpenPGP</guilabel> tab on +the <guilabel>Security</guilabel> settings page; there you will find the +following options:</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Encryption tool</guilabel></term> +<listitem> +<para>Here you can choose if you want to use <application>PGP</application>, +<application>GnuPG</application> or no encryption +software at all; of course, the program you select has to be +installed on your system (it is also important to select the correct +version.)</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Keep passphrase in memory</guilabel></term> +<listitem> +<para>When this option is off, &kmail; will ask for your passphrase each +time you sign a message (before sending) or select an encrypted message; +if you turn this option on, &kmail; will remember your passphrase from +after your first successful input until you finish your &kmail; session. The +passphrase is stored in memory and not written to the hard disk. +If you use one of the Crypto-Plugins or if you use <application>GnuPG</application> +with the gpg-agent then an external program will ask for your passphrase and +optionally remember it for some time.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Always encrypt to self</guilabel></term> +<listitem> +<para>If this option is off and you want to send an encrypted message to somebody, +then you cannot read this message any longer after you have composed and +encrypted it. Turn this option on to keep sent encrypted messages readable for +you too.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show signed/encrypted text after composing</guilabel></term> +<listitem> +<para>This will show you the result of encrypting and signing before the message +gets sent; this way, you can still cancel sending if encrypting failed. It is +strongly recommended to use this option.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Always show the encryption keys for approval</guilabel></term> +<listitem> +<para>This will always open a dialog that lets you choose the keys used for +each recipient when you are sending an encrypted message; if this +option is off, &kmail; will show this dialog only when it cannot +find a key for a recipient or when there are conflicting or unset encryption +preferences.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Automatically sign messages using OpenPGP</guilabel></term> +<listitem><para>This lets you toggle whether to automatically sign your messages +by default; of course, it is still possible to send unsigned messages by deselecting +the icon in the composer window.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Automatically encrypt messages whenever possible</guilabel></term> +<listitem><para>If this option is on, &kmail; will automatically encrypt messages +with the built-in OpenPGP support or the PGP/MIME-Plugin provided that, +for every recipient, a trusted PGP key is found in your keyring and +you did not tell &kmail; not to encrypt messages sent to +certain recipients. If in doubt, &kmail; will ask whether the message +should be encrypted or not.</para></listitem> +</varlistentry> + +</variablelist> + +<para>Now that you have setup the encryption tool you have tell &kmail; which +OpenPGP key you want to use for signing and for encrypting messages; +to do this go to the <link linkend="configure-identity">Identities configuration</link> +and set the key that should be used on the <guilabel>Advanced</guilabel> tab of the +identity configuration.</para> + +<para>Now you are able to sign outgoing messages; to let people send you +encrypted messages and to let them verify your signature you +must send them your public key or upload your public key to a public +<application>PGP</application> key server so that they can fetch your key from there. +To send encrypted messages to other people or to verify their signed +messages you will need their public keys; you can store your public key(s) on a +public <application>PGP</application> key server such as <ulink +url="http://www.cam.ac.uk.pgp.net/pgpnet/">http://www.cam.ac.uk.pgp.net/pgpnet/</ulink>.</para> + +</sect2> + +<sect2 id="pgp-sign-your-messages"> +<title>Sign your Messages</title> + +<para>You can compose your message as usual in the composer +window of &kmail;. Before you send the message, check the <guiicon>Sign Message</guiicon> +icon on the toolbar of the composer window; then, you can send +the message. The identity you are using to write the current message needs to +be connected to an <guilabel>OpenPGP Key</guilabel> in the <guilabel>Identity</guilabel> +section of the <guilabel>Configure</guilabel> dialog. +To sign the message, &kmail; needs to know your <application>PGP</application> +passphrase: if you did not select <guilabel>Keep passphrase in memory</guilabel> in the +<guilabel>Security</guilabel> section, &kmail; will ask you for it; otherwise, +if you have already given the phrase to &kmail;, it will sign the +message without any further prompt.</para> + +</sect2> + +<sect2 id="pgp-encrypt-your-messages"> +<title>Encrypt your Messages</title> + +<para>To send an encrypted message to somebody of whom you have a +public key, you simply create the message in the composer window. +Before you send the message, check the <guibutton>Encrypt +Message</guibutton> button in the toolbar of the composer window; note +that you might not have to check the button if <guilabel>Automatically +encrypt messages whenever possible</guilabel> is selected in +&kmail;'s configuration (see <link linkend="pgp-sign-your-messages">above</link>). +Then send the message.</para> + +<para> +If you checked the <guilabel>Encrypt Message</guilabel> button and &kmail; +cannot find a matching key for a recipient, it will display a list containing +all available keys in the <guilabel>Encryption Key Selection</guilabel> dialog; +if &kmail; finds more than one trusted key for a recipient, it will +display a list containing all matching keys for this recipient. In both +cases you can select the key(s) which should be used for encrypting +this message for the recipient in question. +Using the <guilabel>Remember choice</guilabel> +checkbox you can save your selection for future messages.</para> + +<para>If you are using a key for the first time, there are conflicting +Encryption Preferences, or if <guilabel>Always +show the encryption keys for approval</guilabel> is selected in the +<guilabel>Security</guilabel> section of &kmail;'s configuration dialog +the <guilabel>Encryption Key Approval</guilabel> dialog will appear; +here, you can select different keys for the recipients and can +set the <guilabel>Encryption Preference</guilabel> for each recipient. +The default option, <guilabel>Encrypt whenever encryption is +possible</guilabel>, will automatically encrypt your message if there is a +trusted key for each recipient.</para> + +<para>As mentioned above, you will not be able to read your own encrypted sent +messages if you do not check <guilabel>Always encrypt to self</guilabel> in the +settings' <guilabel>Security</guilabel> page.</para> + +</sect2> + +<sect2 id="pgp-send-your-public-key"> +<title>Send your Public Key</title> + +<para>Prepare a message to the person to whom you want to send your public key; +then, choose, in the composer window's menu, +<menuchoice><guimenu>Attach</guimenu><guimenuitem>Attach My Public +Key</guimenuitem></menuchoice>: this will attach the public key you +defined for the current identity to the message. Now you can send the message.</para> + +<para>Remember that it is not safe at all if you sign the message to make sure +that the receiver will get the correct key: there can be a man-in-the-middle +attack, as somebody can change the key and sign the message with that other +key. That is why the recipient should verify the attached key by checking the +key's fingerprint against the one he received in a secure way from you; have a look +at the <application>PGP</application> documentation for further details.</para> + +</sect2> + +<sect2 id="pgp-you-received-an-encrypted-message"> +<title>You received an encrypted Message</title> + +<para>All you have to do is to select the message in &kmail;. You will be +prompted for your passphrase; then, &kmail; will try to decrypt the message and +show you the plain text if the message had been encrypted with your public +key: if not, then you will not be able to read it. &kmail; stores the messages +encrypted, so nobody can read these messages without knowing your passphrase.</para> + +</sect2> + +<sect2 id="pgp-receiving-a-public-key"> +<title>Receiving a Public Key</title> + +<para>You can receive a public key as an attachment or via http, ftp or a floppy. +Before you can use this key to encrypt a message to the owner of the +key, you should verify the key (check its fingerprint or look for +trusted signatures); then, you can add this key to your public keyring +by typing <userinput><command>pgp</command> <option>-ka</option> +<replaceable>filename</replaceable></userinput> at the command line (if you are using +<application>PGP</application>) or by typing +<userinput><command>gpg</command> <option>--import</option> +<replaceable>filename</replaceable></userinput> at the command line (if you are using +<application>GnuPG</application>). If the key is not certified with a trusted signature +you cannot use it to encrypt messages unless you have signed the key with your key. +</para> + +</sect2> + +</sect1> + +<sect1 id="the-anti-spam-wizard"> +<title>The Anti-Spam Wizard</title> + +<sect2 id="spam-wizard-basics"> +<title>Basics</title> + +<para>&kmail; does not have a built-in spam detection solution: the developers believe +using external, but specialized, tools is the better approach. &kmail; uses these tools +through its flexible filter architecture. The Anti-Spam Wizard helps you with the +initial filter setup. +</para> + +<variablelist> +<varlistentry> +<term>What can the wizard do to help you?</term> +<listitem> +<para>It will give you some choices about how you want the spam filtering to be set up. +Afterwards it will automatically create the appropriate filter rules. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>What are the limitations of the wizard?</term> +<listitem> +<para>It can only initially set up the filters for you; and it will provide a +standard setup. Manual modifications in existing filters are not considered. +Instead, these filters are overwritten by the wizard. +</para> +</listitem> +</varlistentry> +</variablelist> + +<para>You can activate the wizard via <menuchoice><guimenu>Tools</guimenu> +<guisubmenu>Anti-Spam Wizard...</guisubmenu></menuchoice>.</para> + +<para>The wizard scans for known anti-spam tools on your computer. +It is as well possible to use results of spam checks made by your provider +by evaluating some header information which has been added to the messages. +You can let the wizard prepare &kmail; to use one or many of them in parallel. +However, note that anti-spam tool operations are usually time consuming. +&kmail; can appear to be frozen during the scan of the messages for spam, +you may encounter problems with the responsiveness of &kmail;. Please consider +deleting the filter rules created by the wizard if the filtering becomes +too slow for you. +Here are some recommendations regarding the supported tools:</para> + +<variablelist> +<varlistentry> + <term>Bogofilter</term> +<listitem> +<para>Bogofilter is a bayesian filter, that means it's spam detection +relies on an initial training phase. On the other hand, it's a pretty +fast tool. That's why it is recommended to be used by people which +primarily want to have a fast spam detection, and which don't worry +about the little training in the beginning before the detection rate +increases significantly. +</para> +</listitem> +</varlistentry> +<varlistentry> + <term>SpamAssassin</term> +<listitem> +<para>SpamAssassin is a pretty complex tool to fight against spam. +Although it's behavior depends heavily on it's configuration, that +tool can detect spam quite well without any training. However, +scanning a message takes a little longer compared to pure bayesian +filters. Let's say, it's not the tool of choice for people without +some background information about SpamAssassin's capabilities. +</para> +</listitem> +</varlistentry> +<varlistentry> + <term>Annoyance-Filter</term> +<listitem> +<para>Perhaps not so often used until distributions pick it up. +It's clearly a tool for specialists. +</para> +</listitem> +</varlistentry> +<varlistentry> + <term>GMX Spam Filter</term> +<listitem> +<para>Given that you get your mail via the GMX freemail provider, +your messages are scanned for spam. The result of that process is +documented in a special header field of each message. It's possible to +use the content of this header field to sort out spam. There is no +slowdown in the filtering if only this tool is used, as the messages +have already been processed. +</para> +</listitem> +</varlistentry> +</variablelist> + + +</sect2> + +<sect2 id="spam-wizard-advanced"> +<title>Advanced</title> + +<para>Here are the details of how the wizard works: &kmail; can use several +external tools to detect spam messages; it will try to automatically find +out which of those tools are installed on your box and will show you these +tools in a list. The list is ordered by the average speed of the filtering +process of the tools. You can mark the tools which you want +to be used by &kmail; to detect spam. Of course, you +can close the wizard, install a tool, and restart the wizard again. +</para> + +<para>If you have marked at least one tool, KMail is able to provide filters +which allow the classification of the messages as spam or not spam. It will +also provide actions to let you manually classify messages. These actions will +be available via the menu and via toolbar icons. +If any of the tools you selected support Bayesian filtering (&ie; a method +to detect spam based on statistical analysis of the messages) then these +messages are not only marked but additionally transfered to the tools to +let them learn so they can improve their detection rate. +</para> + +<para>On the second page, there you will be able to select some additional +actions to be done in &kmail; with regard to spam messages: if you +want messages detected as spam to be moved into a certain folder, please select +the appropriate folder and mark the <guilabel>Move known spam to:</guilabel> +option; if messages detected as spam should additionally be marked as read, +then mark the <guilabel>Mark detected spam messages as read</guilabel> option. +</para> + +<para>Having checked at least one of the available tools will allow you to +let the wizard finish the filter setup. The wizard will not take any +modifications in existing filters formerly created by the wizard into +consideration but will either append new filters or replace existing filters +in any case; you may want to inspect the result of this process in the +<link linkend="filter-dialog">Filter Dialog</link>. +The wizard will also create toolbar buttons for marking messages as spam or +as ham; keep in mind that classifying messages as spam will also move those +messages to the folder you had specified for spam messages, if you haven't +deselected the appropriate option. +</para> + +</sect2> + +<sect2 id="spam-wizard-details"> +<title>Some More Details for Experts</title> + +<para>The wizard uses information stored in a special configuration file named +<filename>kmail.antispamrc</filename> (stored in the global or local KDE +config directory). It will first check the global config file and then the local +config file: if the local config file contains entries with higher (newer) +version numbers per-tool the configuration data from the local file for that +tool is used; that way, both administrators and users can update the +wizard configuration. +</para> + +<para>The local detection of spam messages is achieved by creating +<guilabel>pipe through</guilabel> actions per-tool within a +special filter. Another filter contains rules to check for detected spam +messages and actions to mark them and (optionally, depending on the choice +in the wizard) to move them into a folder. Both filters are configured to +be applied on incoming messages and on manual filtering. +</para> + +<para>Two filters are needed for the classification of ham and spam. They +contain actions to mark the messages appropriately. As mentioned above, the filter +for classification as spam can have another action to move the message into a +predefined folder. If the selected tools support Bayesian filtering, +the wizard will create additional filter actions to pass the messages to the +tools (via <guilabel>execute command</guilabel> actions) in the +appropriate learn mode. +</para> + +<para>If you want to fine-tune the filtering process, you might be interested in the +chapter about <link linkend="filter-optimization">Filter Optimization</link>.</para> + +</sect2> + +</sect1> + +<sect1 id="the-anti-virus-wizard"> +<title>The Anti-Virus Wizard</title> + +<sect2 id="virus-wizard-basics"> +<title>Basics</title> + +<para>&kmail; does not have a built-in virus detection solution: the developers believe +using external, but specialized, tools is the better approach. &kmail; uses these tools +through its flexible filter architecture. The Anti-Virus Wizard helps you with the +initial filter setup. +</para> + +<variablelist> +<varlistentry> +<term>What can the wizard do to help you?</term> +<listitem> +<para>It will give you some choices about how you want virus filtering to be set up. +Afterwards it will automatically create the appropriate filter rules. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>What are the limitations of the wizard?</term> +<listitem> +<para>It can only initially set up the filters for you; and it will provide a +standard setup. Modifying existing filters is not yet possible. +</para> +</listitem> +</varlistentry> +</variablelist> + +<para>You can activate the wizard via <menuchoice><guimenu>Tools</guimenu> +<guisubmenu>Anti-Virus Wizard...</guisubmenu></menuchoice>.</para> + +</sect2> + +<sect2 id="virus-wizard-advanced"> +<title>Advanced</title> + +<para>The Anti-Virus Wizard basically works exactly as the +<link linkend="the-anti-spam-wizard">Anti-Spam Wizard</link>. +Here are the details of how the wizard works: &kmail; can use several +external tools to detect messages containing viruses; it will try to automatically find +out which of those tools are installed on your box and will show you the +result of the search for each tool. You can mark the tools which you want +to be used by &kmail; to detect viruses; marking tools which were not found is +not possible because the appropriate checkboxes are disabled. Of course, you +can close the wizard, install a tool, and restart the wizard again. +</para> + +<para>If you have marked at least one tool you will be able to select some actions +to be done in &kmail; with regard to messages containing viruses: to let &kmail; detect +messages containing viruses you definitely should mark the <guilabel>Check messages using the +anti-virus tools</guilabel> option; if you want messages detected as +virus-infected to be moved into a certain folder, please select the appropriate folder and +mark the <guilabel>Move detected viral messages to the selected folder</guilabel> +option; if messages detected as virus-infected should additionally be marked as read, +then mark the <guilabel>Additionally, mark detected viral messages as read</guilabel> option. +</para> + +<para>Having checked at least one of these last options will allow you to +let the wizard finish the filter setup. The wizard will not take any existing +filter rules into consideration but will append new rules in any case; you +may want to inspect the result of this process in the +<link linkend="filter-dialog">Filter Dialog</link>. +</para> + +</sect2> + +<sect2 id="virus-wizard-details"> +<title>Details</title> + +<para>The wizard uses information stored in a special configuration file named +<filename>kmail.antivirusrc</filename> (stored in the global or local KDE +config directory). It will first check the global config file and then the local +config file: if the local config file contains entries with higher (newer) +version numbers per-tool the configuration data from the local file for that +tool is used; that way, both administrators and users can update the +wizard configuration. +</para> + +<para>The detection of messages containing viruses is achieved by creating +<guilabel>pipe through</guilabel> actions per-tool within a +special filter. Another filter contains rules to check for detected viral +messages and actions to mark them and (optionally, depending on the choice +in the wizard) to move them into a folder. Both filters are configured to +be applied on incoming messages and on manual filtering. +</para> + +</sect2> + +</sect1> + +</chapter> diff --git a/doc/knode/Makefile.am b/doc/knode/Makefile.am new file mode 100644 index 000000000..692f3ff3a --- /dev/null +++ b/doc/knode/Makefile.am @@ -0,0 +1,9 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + +# $(srcdir)/translation.po: $(srcdir)/german_original.docbook +# xml2pot $(srcdir)/german_original.docbook > german.pot +# msgmerge -o $(srcdir)/translation.po $(srcdir)/translation.po german.pot +# rm german.pot + diff --git a/doc/knode/commands.docbook b/doc/knode/commands.docbook new file mode 100644 index 000000000..47a96ffe1 --- /dev/null +++ b/doc/knode/commands.docbook @@ -0,0 +1,1890 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd"> --> + +<chapter id="commands"> +<title>Command reference</title> + +<para>The following keybindings assume you did not change the default +settings.</para> + +<sect1 id="knode-mainwindow"> +<title>The main &knode; window</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 As...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Saves the selected article in a file.</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 selected article.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu> +File</guimenu> +<guimenuitem>Send Pending Messages</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +The messages in the <guilabel>Outbox</guilabel> folder are sent.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu> +File</guimenu> +<guimenuitem>Stop Network</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Disconnects the current connection to a newsserver.</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 &knode;.</action> +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2> +<title> +The <guimenu>Edit</guimenu> menu</title> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>C</keycap> +</keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Copy</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Copy the selected text to the clipboard.</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 the whole article.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut> +<keycap>F4</keycap></shortcut><guimenu>Edit</guimenu> +<guimenuitem>Search Articles...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens the <guilabel>Search for Articles</guilabel> dialog box for searching in the active group.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>F</keycap> +</keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Find in Article...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +To be written +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Fetch Article with ID...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Enables the download of an article with a specified article-ID.</action> +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2> +<title> +The <guimenu>View</guimenu> menu</title> + +<!--Headers and Attachments missing--> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Show/Hide Threads</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +When this is activated, &knode; shows discussions as a tree view in the article view.</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Expand All Threads</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +When this is activated, &knode; shows the complete threads; this is +only functional when <guilabel>Show threads</guilabel> +is active.</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Collapse All Threads</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +When this is activated, &knode; shows no threads; this is only +functional when <guilabel>Show threads</guilabel> is active.</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>T</keycap></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Toggle Subthread</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Toggles between showing and collapsing the selected thread.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Filter</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Allows you to choose a filter for the article view.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Sort</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Allows you to sort the article view.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>F5</keycap></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Refresh List</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Refreshes the article view</action> +</para> +</listitem> +</varlistentry> +<!--varlistentry> +<term> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Show all headers</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +When this setting is activated, &knode; shows the complete article header in the article window.</action> +</para> +</listitem> +</varlistentry--> +<varlistentry> +<term> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Unscramble (ROT 13)</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +When this setting is activated, &knode; shows all characters of the complete article rotated by 13 characters.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Verify PGP signature</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action>Checks the PGP signature in the article.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>V</keycap></shortcut> +<guimenu>View</guimenu> +<guimenuitem>View Source</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +The source code of the active article is opened in a new window.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>X</keycap></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Use Fixed Font</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Activates the configured fixed-width font for the viewer.</action> +</para> +</listitem> +</varlistentry> + +<!--Fancy Formatting Y is missing--> + +<varlistentry> +<term> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Charset</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Here you can configure the charset which is used for the articles.</action> +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2> +<title> +The <guimenu>Go</guimenu> menu</title> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>P</keycap></shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Previous Article</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Jumps to previous article in the article view.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>N</keycap></shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Next Article</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Jumps to next article in the article view.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Alt;&Shift;<keycap>Space</keycap></keycombo> +</shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Next Unread Article</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Jumps to the next unread article, and to the first unread article of the next newsgroup if necessary.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Shift;<keycap>Space</keycap></keycombo></shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Next Unread Thread</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Jumps to the next unread thread, and to the next unread thread in the next newsgroup if necessary.</action> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>-</keycap></shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Previous Group</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Jumps to the previous news group in the folder view</action> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>+</keycap></shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Next Group</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Jumps to the next newsgroup in the folder view</action> +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2> +<title>The <guimenu>Account</guimenu> menu</title> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<guimenu>Account</guimenu> +<guimenuitem>Get New Articles in All Groups</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Connects with the active account and fetches any new messages.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Account</guimenu> +<guimenuitem>Get New Articles in All Accounts</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Connects with all account and fetches any new messages.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Account</guimenu> +<guimenuitem>Subscribe to Newsgroups...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens the Dialog Box for subscribing to newsgroups for the active account.</action> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Account</guimenu> +<guimenuitem>Expire All Groups</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Here you can expire all groups of an account manually.</action> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Account</guimenu> +<guimenuitem>Account Properties</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens the properties dialog for the active account.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Account</guimenu> +<guimenuitem>Delete Account</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Deletes the active account and all subscribed newsgroups therein.</action> +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2> +<title> +The <guimenu>Group</guimenu> menu</title> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<guimenu>Group</guimenu> +<guimenuitem>Get New Articles</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Connects with the active account and fetches any new messages.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Group</guimenu> +<guimenuitem>Expire Group</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Checks if there are any old articles and, if so, deletes them.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Group</guimenu> +<guimenuitem>Reorganize Group</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Rebuilds the article view by using the configured sortings.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Group</guimenu> +<guimenuitem>Mark All as Read</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Sets the status of all articles in the active newsgroup to read.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Group</guimenu> +<guimenuitem>Mark All as Unread</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Sets the status of all articles in the active newsgroup to unread.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Group</guimenu> +<guimenuitem>Mark Last as Unread</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +To be written.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Group</guimenu> +<guimenuitem>Group Properties</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens the dialog for the group properties.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Group</guimenu> +<guimenuitem>Unsubscribe From Group</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Unsubscribes from the active newsgroup</action> +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + + +<sect2> +<title> +The <guimenu>Folder</guimenu> menu</title> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>New Folder</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Creates a new main folder.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>New Subfolder</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Creates a new subfolder.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Rename Folder</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Here you can rename the active folder.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Import MBox Folder...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +With this function it is possible to import an MBox folder into the active folder.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Export as MBox Folder...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +With this function you can export the active folder as an MBox folder.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Compact Folder</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Removes all deleted articles from the active folder.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Compact All Folders</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Removes all deleted articles from the every folder.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Empty Folder</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Deletes all articles from the active folder.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Folder</guimenu> +<guimenuitem>Delete Folder</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Deletes the active folder.</action> +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2> +<title> +The <guimenu>Article</guimenu> menu</title> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo> +</shortcut> +<guimenu>Article</guimenu> +<guimenuitem>Post to Newsgroup...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens the Composer, with the settings for writing new articles set to those of the active newsgroup.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>R</keycap></shortcut> +<guimenu>Article</guimenu> +<guimenuitem>Followup to Newsgroup</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens the Composer for writing a followup, with the content of the active article.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>A</keycap></shortcut> +<guimenu>Article</guimenu> +<guimenuitem>Reply by Email...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens the Composer for writing an e-mail to the author of the active article.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>F</keycap></shortcut> +<guimenu>Article</guimenu> +<guimenuitem>Forward by Email...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens the Composer for forwarding the active article as e-mail.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>D</keycap></shortcut> +<guimenu>Article</guimenu> +<guisubmenu>Mark as Read</guisubmenu> +</menuchoice> +</term> +<listitem> +<para> +Set the status of the active article to<quote> +read</quote> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>U</keycap></shortcut> +<guimenu>Article</guimenu> +<guisubmenu>Mark as Unread</guisubmenu> +</menuchoice> +</term> +<listitem> +<para> +Set the status of the active article to<quote> +unread</quote> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo></shortcut> +<guimenu>Article</guimenu> +<guisubmenu>Mark Thread as Read</guisubmenu> +</menuchoice> +</term> +<listitem> +<para> +Set the status of the active thread to<quote> +read</quote> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo></shortcut> +<guimenu>Article</guimenu> +<guisubmenu>Mark Thread as Unread</guisubmenu> +</menuchoice> +</term> +<listitem> +<para> +Set the status of the active thread to<quote> +unread</quote> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Article</guimenu> +<guimenuitem>Cancel Article</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Generate a message which deletes the active Article in Usenet; you can +only use this with your own articles.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Article</guimenu> +<guimenuitem>Supersede Article</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens the Composer with the content of the active article; when this article is posted it overwrites the original article. You can only use this with your own articles.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>O</keycap></shortcut> +<guimenu>Article</guimenu> +<guimenuitem>Open in Own Window</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +The active article is opened in a new window.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>E</keycap></shortcut> +<guimenu>Article</guimenu> +<guimenuitem>Edit Article...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens the Composer for editing the active article;</action> +you can only use this in the <guilabel> +Outbox</guilabel> +and <guilabel> +Drafts</guilabel> +folders.</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>Delete</keycap></shortcut> +<guimenu>Article</guimenu> +<guimenuitem>Delete Article</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Deletes the active article.</action> +You can only use this in the <guilabel> +Outbox</guilabel> +and <guilabel> +Drafts</guilabel> + folders.</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Article</guimenu> +<guimenuitem>Send Now</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Sends the active article.</action> +You can only use this in the <guilabel> +Outbox</guilabel> +and <guilabel> +Drafts</guilabel> +folders.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2> +<title> +The <guimenu>Scoring</guimenu> menu</title> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo></shortcut> +<guimenu>Scoring</guimenu> +<guimenuitem>Edit Scoring Rules...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +The dialog to edit the scoring rules will be opened.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Scoring</guimenu> +<guimenuitem>Recalculate Scores</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +The scores will be reset and recalculated.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>L</keycap></keycombo></shortcut> +<guimenu>Scoring</guimenu> +<guimenuitem>Lower Score for Author...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Creates a rule for lowering the score of all articles posted by the author of the active article.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>I</keycap></keycombo></shortcut> +<guimenu>Scoring</guimenu> +<guimenuitem>Raise Score for Author...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Creates a rule for raising the score of all articles posted by the author of the active article.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>W</keycap></shortcut><guimenu>Scoring</guimenu> +<guimenuitem>Watch Thread</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Sets the score for this thread to the configured score of watched threads (standard = 100).</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycap>I</keycap></shortcut> +<guimenu>Scoring</guimenu> +<guimenuitem>Ignore Thread</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Sets the score for this thread to the configured score of ignored threads (standard = -100).</action> +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2> +<title> +The <guimenu>Settings</guimenu> menu</title> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Show/Hide Toolbar</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +This option toggles whether the toolbar is shown or not.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Show/Hide Statusbar</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +This option toggles whether the statusbar is shown or not.</action> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo> +</shortcut> +<guimenu>Settings</guimenu> +<guimenuitem>Show/Hide Group View</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +This option toggles whether the group list is shown or not.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>H</keycap></keycombo> +</shortcut> +<guimenu>Settings</guimenu> +<guimenuitem>Show/Hide Header View</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +This option toggles whether the header view is shown or not.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>J</keycap></keycombo> +</shortcut> +<guimenu>Settings</guimenu> +<guimenuitem>Show Article Viewer</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +This option toggles whether the article is shown or not.</action> +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Shortcuts...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens a dialog for configuring the key bindings.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Toolbars...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens a dialog for configuring the toolbars.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure &knode;...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens a dialog for configuring &knode;.</action> +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2> +<title> +The <guimenu>Help</guimenu> menu</title> + +&help.menu.documentation; + +</sect2> +</sect1> + +<sect1 id="knode-editorwindow"> +<title>The composer menus.</title> + +<sect2> +<title> +The <guimenu>File</guimenu> menu</title> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>Return</keycap></keycombo></shortcut> +<guimenu>File</guimenu> +<guimenuitem>Send Now</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Sends the current article immediately.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Send Later</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Stores the current article in the <guilabel> +Outbox</guilabel> +to be sent later.</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Save as Draft</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Saves the current article in the <guilabel> +Drafts</guilabel> +folder, so you can finish editing it another time.</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Delete</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Deletes the current article, closing the editor.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo></shortcut> +<guimenu>File</guimenu> +<guimenuitem>Close</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Closes the editor window</action> +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2> +<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> +Undo the last edit.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>Shift</keycap><keycap>Z</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Redo</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Redo the last action undone with the <guimenuitem> +Undo</guimenuitem> +menu entry.</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 text to the clipboard, deleting it from the editor window.</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 selected text 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> +Pastes the current contents of the clipboard into the editor window.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Paste as Quotation</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Pastes the current contents of the clipboard into the editor window with +a quote character </action> (<quote>></quote>) at the beginning of each +line. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Select All</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Selects all the text in the editor window.</action> +</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> +Opens the Find dialog.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Replace...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens the Replace dialog.</action> +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2> +<title> +The <guimenu>Attach</guimenu> menu</title> +<para> +<variablelist> +<varlistentry> +<term> +<menuchoice> +<guimenu>Attach</guimenu> +<guimenuitem>Append Signature</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Inserts your signature at the end of the article you are editing.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Attach</guimenu> +<guimenuitem>Insert File...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Inserts the contents of a file into the editor window.</action> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Attach</guimenu> +<guimenuitem>Insert File (in a box)...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Inserts the contents of a file into the editor window and puts a box around of it.</action> +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term> +<menuchoice> +<guimenu>Attach</guimenu> +<guimenuitem>Attach File...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Inserts a file as an attachment.</action> +</para> +</listitem> +</varlistentry> +</variablelist> +</para> +</sect2> + +<sect2> +<title> +The <guimenu>Options</guimenu> menu</title> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<guimenu>Options</guimenu> +<guimenuitem>Send News-Article</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Toggles whether the message is to be sent as an article or not.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Options</guimenu> +<guimenuitem>Send Email</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Toggles whether the message is to be sent as an email or not; if it's configured, an external editor will be activated.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Options</guimenu> +<guimenuitem>Set Charset</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Here you can configure the charset used for this article; normally you use us-ascii for English-speaking areas.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Options</guimenu> +<guimenuitem>Word Wrap</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Toggles the word wrapping in the editor on or off.</action> +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2> +<title> +The <guimenu>Tools</guimenu> menu</title> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Add Quote Characters</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> + +Puts <quote>></quote> in front of the marked lines. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Remove Quote Characters</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Removes the quote characters at the beginning of the marked lines.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Add Box</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Puts the marked lines in an ASCII box.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Remove Box</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Removes the ASCII box around the marked area.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Sign Article with PGP</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Signs the article with PGP.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Get Original Text (not rewrapped)</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Rebuilds the original posting when answering to an article.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Scramble (Rot-13)</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Encrypts the marked text by rotating every character 13 characters of the alphabet.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Start External Editor</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Start the external editor (if one is configured) with the current contents of the editor window.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo></shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Spelling...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens a dialog box to check your spelling.</action> +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2> +<title> +The <guimenu>Settings</guimenu> menu</title> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Show Toolbar</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Toggles whether the toolbar should be shown or not.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Show Statusbar</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Toggles whether the statusbar should be shown or not.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Shortcuts...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens a dialog for configuring the key bindings.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Toolbars...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Opens a dialog for configuring the toolbars.</action> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure KNode...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action> +Open the &knode; Preferences dialog.</action> +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2> +<title>The <guimenu>Help</guimenu> menu</title> + +&help.menu.documentation; + +</sect2> + +</sect1> +</chapter> diff --git a/doc/knode/credits.docbook b/doc/knode/credits.docbook new file mode 100644 index 000000000..093c16851 --- /dev/null +++ b/doc/knode/credits.docbook @@ -0,0 +1,55 @@ +<chapter id="credits"> +<title>Credits and License</title> + +<para>&knode;</para> + +<para>Program Copyright 1999, 2000, 2001, 2002 KNode developers</para> + +<itemizedlist> +<title>Developers</title> +<listitem> +<para>Christian Gebauer <email>gebauer@kde.org</email></para> +</listitem> +<listitem> +<para>Christian Thurner <email>cthurner@web.de</email></para> +</listitem> +<listitem> +<para>Dirk Mueller <email>mueller@kde.org</email></para> +</listitem> +<listitem> +<para>Mark Mutz <email>mutz@kde.org</email></para> +</listitem> +<listitem> +<para>Roberto Teixeira <email>roberto@kde.org</email></para> +</listitem> +<listitem> +<para>Mathias Waack <email>mathias@atoll-net.de</email></para> +</listitem> +</itemizedlist> + +<itemizedlist> +<title>Documentation</title> +<listitem> +<para>Copyright 2000, 2001 Stephan +Johach<email>lucardus@onlinehome.de</email></para> +</listitem> +<listitem> +<para>Copyright 2001, 2002 Thomas Schütz <email> +Thomas.Schuetz@gmx.li</email></para> +</listitem> +</itemizedlist> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +<para>Thanks go to the &knode; developers who answered all my stupid +questions with patience. Then Thomas Diehl and Matthias Kiefer who +always were competent contacts regards to translation. Many Thanks to +Malcolm Hunter who checked this english translation. Not to forget +Michael McBride, always there to help me out with +documentation-related and general stuff, and everybody else in the +&kde; Team who contributed to the creation of this document.</para> + +&underFDL; <!-- FDL license for the documentation --> +&underGPL; <!-- GPL License for the application --> + +</chapter> diff --git a/doc/knode/eyes.png b/doc/knode/eyes.png Binary files differnew file mode 100644 index 000000000..f2eefe3a8 --- /dev/null +++ b/doc/knode/eyes.png diff --git a/doc/knode/faq.docbook b/doc/knode/faq.docbook new file mode 100644 index 000000000..6f37d8765 --- /dev/null +++ b/doc/knode/faq.docbook @@ -0,0 +1,189 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd"> +--> +<chapter id="faq"> +<title>Questions and Answers</title> + +<qandaset> +<qandaentry> +<question> +<para>I have installed &kde; 3, but &knode; does not exist in the +<guimenu>K</guimenu> Menu.</para> + </question> +<answer> +<para>Does the <guisubmenu>Internet</guisubmenu>entry exist? If not, +maybe the kdenetwork package isn't installed (perhaps because your +distribution possibly doesn't do this for you); if the entry is there, +but you do not have a <guimenuitem>KNode</guimenuitem> item +in it, you should try to open a &konsole; and run &knode; from +there. Type</para> + +<screen> +<prompt>%</prompt> <userinput><command>knode &</command></userinput> +</screen> + +<para>If an error message appears that tells you that &knode; could +not be started or found please check whether the file +<filename>knode</filename> exists in <filename +class="directory">$<envar>KDEDIR</envar>/bin</filename> and that its +permissions are correctly set.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +When I start &knode;, a message appears in the task bar but suddenly +disappears without &knode; being started.</para> +</question> +<answer> +<para>Try to start &knode; from the &konsole; (see previous question) +and keep attention for the messages displayed there: if they do not +make sense to you mark them with your mouse and copy it to the +clipboard; then, ask for help on one of the &kde; mailing lists or +&kde; news groups.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>I need an important article, but &knode; doesn't have it any +more; where can I find this article?</para> +</question> +<answer> +<para>You can find some extensive usenet archives at +<ulink +url="http://groups.google.com/usenet/">groups.google.com</ulink> or +<ulink url="http://av.com">AltaVista</ulink>; they even contain +articles that are several years old.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I open and read several articles at the same time?</para> +</question> +<answer> +<para> Open the article with <guimenuitem>Open in own +window</guimenuitem>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>My articles do not appear in the newsgroup.</para> +</question> +<answer> +<para>When you publish an article it may be some time until your +news server has it; wait several hours before you send the article +again.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>I want to keep an article; how do I archive it?</para> +</question> +<answer> +<para>Choose the article in the article +view and then use +<menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice> +to open a file dialog; you can then save the article to a file. Another +possibility is to copy the article to a folder.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Some set headers do not appear for several articles in the +article window; am I doing something wrong?</para> +</question> +<answer> +<para>This is not unusual because many headers are optional and often +not contained in articles; in this case &knode; does not show those +header lines.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Sometimes I see an article which refers to other articles but +&knode; does not show any references; why is that?</para> +</question> +<answer> +<para>This happens when somebody posted an article in another news +group and checked the option <guilabel>Followup To</guilabel>; the +article in question is then sent to your news group, but the referring +article is absent. In many cases the poster tells the reason for his +choice to set a followup.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>When I want to answer an article an error message appears +telling me that the external editor could not be started, but the +editor is correctly set.</para> +</question> +<answer> +<para>Have a look whether you entered the place-holder for a filename +after the editor command; if not, enter it. If you want, for example, to +use &kedit; enter <userinput><command>kedit</command><token> +%f</token></userinput></para> +<para>If the <token>%f</token> is absent, your editor cannot be +run.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Why can I not receive data from my local news server?</para> +</question> +<answer> +<para>If you use &knode; together with with a local news server, you +must make sure that this server is correctly set up and started; for +further details, please consult the documentation of your local news +server.</para> +<tip> +<para> +The availability of the local news server can easily be verified with +the <command>telnet</command> program: open a console and type:</para> + +<screen> +<prompt>%</prompt> <userinput><command>telnet</command> <parameter>localhost nntp</parameter></userinput> +</screen> + +<para>Followed by that, the news server should respond with:</para> + +<screen> +<computeroutput> +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'. +200 Leafnode NNTP Daemon, version 1.9.16 running at konqi.org +</computeroutput> +</screen> + +<para>You can quit the <command>telnet</command> session with:</para> + +<screen> +<prompt>%</prompt> <userinput>quit</userinput> +</screen> + +<para>If that does not work there is either no local news server +set up or the server was not started; in this case, please consult the +documentation of your local news server.</para> +</tip> + +<para>If you are trying to connect to a news server on the Internet +you need, of course, an open (dial-in) connection and to have set +up &knode; to use your <acronym>ISP</acronym>'s news server; your +<acronym>ISP</acronym> should be able to give you information about +which news servers you can use.</para> +</answer> +</qandaentry> + +</qandaset> + + +</chapter> diff --git a/doc/knode/gloss.docbook b/doc/knode/gloss.docbook new file mode 100644 index 000000000..5e04fd0d3 --- /dev/null +++ b/doc/knode/gloss.docbook @@ -0,0 +1,257 @@ +<glossary id="glossary"> +<title>Glossary</title> + +<glossdiv> +<title>A</title> +<glossentry id="gloss-article"> +<glossterm>Article</glossterm> +<glossdef> +<para>An <glossterm>article</glossterm> in the sense of +newspapers: special <glossterm>articles</glossterm> are, for example, +followups; replies are not <glossterm>articles</glossterm> but +Email.</para> +</glossdef> +</glossentry> +</glossdiv> + +<glossdiv> +<title>C</title> + +<glossentry id="gloss-cancel"> +<glossterm>Canceling</glossterm> +<glossdef> +<para>To delete one of your articles from the newsserver: the newsreader +generates a special control message to tell the server to delete this +article.</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-crossposting"> +<glossterm>Crossposting</glossterm> +<glossdef> +<para>The posting of an article in several newsgroups; this is very +often disliked, because it disturbs the topic-oriented association of +the newsgroups.</para> +</glossdef> +</glossentry> +</glossdiv> + +<glossdiv> +<title>E</title> + +<glossentry id="gloss-expire"> +<glossterm>Expire</glossterm> +<glossdef> +<para><glossterm>Articles</glossterm> can not be held for eternity +because of harddisk limits. Because of this there is usually a program +called <application>expire</application> on most computer +systems; this program deletes all articles which are older than a +configured number of days. &knode; includes this functionality on its +own.</para> +</glossdef> +</glossentry> +</glossdiv> + +<glossdiv> +<title>F</title> +<glossentry id="gloss-faq"> +<glossterm><acronym>FAQ</acronym></glossterm> +<glossdef> +<para><acronym>FAQ</acronym> is the acronym for <quote>Frequently +Asked Questions</quote>.</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-follow-up"> +<glossterm>Followup</glossterm> +<glossdef> +<para>An <glossterm>article</glossterm> which is written as an answer +to another <glossterm>article</glossterm>.</para> +</glossdef> +</glossentry> +</glossdiv> + +<glossdiv> +<title>G</title> +<glossentry id="gloss-gknsa"> +<glossterm><acronym>GNKSA</acronym></glossterm> +<glossdef> +<para><acronym>GNKSA</acronym> is a kind of seal-of-approval for +newsreaders; you can get more information at <ulink +url="http://www.gnksa.org">http://www.gnksa.org</ulink>.</para> +</glossdef> +</glossentry> +</glossdiv> + +<glossdiv> +<title>H</title> +<glossentry id="gloss-header"> +<glossterm>Header</glossterm> +<glossdef> +<para>The Header of an <glossterm>article</glossterm> contains +information about the sender, the subject, and the newsgroup of the +article.</para> +</glossdef> +</glossentry> +</glossdiv> + +<glossdiv> +<title> +K</title> +<glossentry id="gloss-killfile"> +<glossterm>Killfile</glossterm> +<glossdef> +<para>This is a functionality of a newsreader to hide +<glossterm>articles</glossterm> of a determined sender or +with certain contents.</para> +</glossdef> +</glossentry> +</glossdiv> + +<glossdiv> +<title>M</title> +<glossentry id="gloss-message-id"> +<glossterm>Message-ID</glossterm> +<glossdef> + +<para>The <glossterm>Message-ID</glossterm> of an article is a clear +mark for the newsserver to identify the article. A +<glossterm>Message-ID</glossterm> should not be used twice in the +whole usenet for about 2 years; wrong or double +<glossterm>Message-IDs</glossterm> could cause problems when +forwarding them and could overwrite other articles.</para> +</glossdef> +</glossentry> +</glossdiv> + +<glossdiv> +<title>N</title> +<glossentry id="gloss-newbie"> +<glossterm>Newbie</glossterm> +<glossdef> +<para>Somebody who is new somewhere, in relationship to usenet: +somebody who is new to the newsgroup, or new to usenet in +general.</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-newsgroup"> +<glossterm>Newsgroup</glossterm> +<glossdef> +<para>A kind-of bulletin board in the usenet about a special topic or +a group of topics. This is where you post your +<glossterm>articles</glossterm>.</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-newsreader"> +<glossterm>Newsreader</glossterm> +<glossdef> +<para>A program for reading and writing <glossterm>news</glossterm>.</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-nntp"> <glossterm> +<acronym><acronym>NNTP</acronym></acronym> +</glossterm> +<glossdef> +<para>Network News Transport Protocol; this is the protocol which +defines how the articles in the usenet are spread.</para> +</glossdef> +</glossentry> +</glossdiv> + +<glossdiv> +<title>P</title> + +<glossentry id="gloss-port"> +<glossterm>Port</glossterm> +<glossdef> +<para>A kind-of address for the application to listen for data on and +for connecting to another computer; the standard-port for the +connection between the newsreader and the newsserver is 119.</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-pgp-signature"> +<glossterm>PGP-Signature</glossterm> +<glossdef> +<para>A digital signature; you can use it to determine whether the document +has been changed since it was signed or if it is the original text from +the author.</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-posting"> +<glossterm>Posting</glossterm> +<glossdef> +<para>Either an <glossterm>article</glossterm> which is sent to usenet or the +act of sending itself; you are <quote>posting</quote> an +<glossterm>article</glossterm> into a newsgroup.</para> +</glossdef> +</glossentry> +</glossdiv> + +<glossdiv> +<title>Q</title> + +<glossentry id="gloss-quoting"> +<glossterm>Quoting</glossterm> +<glossdef> +<para>This is the act of citing of an article to which you are answering: +you quote the original <glossterm>article</glossterm> to make clear +which passages of text your answer refers to.</para> +</glossdef> +</glossentry> +</glossdiv> + +<glossdiv> +<title>R</title> +<glossentry id="gloss-reply"> + +<glossterm>Reply</glossterm> +<glossdef> +<para>A <glossterm>reply</glossterm> is an answer to the author of an +article by e-mail.</para> +</glossdef> +</glossentry> +</glossdiv> + +<glossdiv> +<title>S</title> + +<glossentry id="gloss-scoring"> +<glossterm>Scoring</glossterm> +<glossdef> + +<para>This is the valuation of an article or a thread.</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-signature"> +<glossterm>Signature</glossterm> +<glossdef> +<para>A <glossterm>signature</glossterm> is a personal sign of the +author which is attached at the end of the normal contents of the article; +it is like a visiting card — very often there are e-mail addresses, a +homepage <acronym>URL</acronym> or other personal data. The +<glossterm>signature</glossterm> should not be longer than 4 lines. Note that +the <glossterm>signature</glossterm> should not be mixed up with the +<glossterm>PGP-signature</glossterm>.</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-supersede"> +<glossterm>Supersede</glossterm> +<glossdef> + +<para>This is the overwriting of an existing article: the newsreader +generates a special article with a control message in the header which +tells the newsserver to overwrite the existing article with this +one.</para> + +</glossdef> +</glossentry> +</glossdiv> + +</glossary> diff --git a/doc/knode/greyball.png b/doc/knode/greyball.png Binary files differnew file mode 100644 index 000000000..65335f182 --- /dev/null +++ b/doc/knode/greyball.png diff --git a/doc/knode/greyballchk.png b/doc/knode/greyballchk.png Binary files differnew file mode 100644 index 000000000..f5c86586d --- /dev/null +++ b/doc/knode/greyballchk.png diff --git a/doc/knode/index.docbook b/doc/knode/index.docbook new file mode 100644 index 000000000..29eeb14ba --- /dev/null +++ b/doc/knode/index.docbook @@ -0,0 +1,130 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&knode;"> + <!ENTITY package "kdepim"> + <!ENTITY introduction SYSTEM "introduction.docbook"> + <!ENTITY commands SYSTEM "commands.docbook"> + <!ENTITY faq SYSTEM "faq.docbook"> + <!ENTITY credits SYSTEM "credits.docbook"> + <!ENTITY install SYSTEM "install.docbook"> + <!ENTITY journey SYSTEM "journey.docbook"> + <!ENTITY using-firststart SYSTEM "using-firststart.docbook"> + <!ENTITY using-subscribing SYSTEM "using-subscribing.docbook"> + <!ENTITY using-morefeatures SYSTEM "using-morefeatures.docbook"> + <!ENTITY more SYSTEM "more.docbook"> + <!ENTITY glossary SYSTEM "gloss.docbook"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> + +<!--TODO: PGP-Option for encoding? + Exchange german links (find "(german" ) + Maybe complete the <accels> of the menus + After that set version to 0.7.1 --> +<book lang="&language;"> + +<bookinfo> +<title>The &knode; manual</title> + +<authorgroup> +<author> +<firstname>Stephan</firstname><surname>Johach</surname> +<affiliation><address><email>lucardus@onlinehome.de</email></address> +</affiliation> +</author> + +<author> +<firstname> Thomas</firstname> <surname>Schütz</surname> +<affiliation> <address> <email>Thomas.Schuetz@gmx.li</email> </address> +</affiliation> +</author> + +<othercredit role="developer" > +<firstname> Christian</firstname> <surname> Gebauer</surname> +<contrib> Developer and maintainer</contrib> +<affiliation> <address> <email>gebauer@kde.org</email> </address> </affiliation> +</othercredit> + +<othercredit role="developer"> +<firstname> Christian</firstname> <surname> Thurner</surname> +<contrib> Developer</contrib> +<affiliation> <address> <email>cthurner@web.de</email> </address> </affiliation> +</othercredit> + +<othercredit role="developer"> +<firstname> Dirk</firstname> <surname> Mueller</surname> +<contrib> Developer</contrib> +<affiliation> <address> <email>mueller@kde.org</email> </address> </affiliation> +</othercredit> + +<othercredit role="developer"> +<firstname> Mark</firstname> <surname> Mutz</surname> +<contrib> Developer</contrib> +<affiliation> <address> <email>mutz@kde.org</email> </address> </affiliation> +</othercredit> + +<othercredit role="developer"> +<firstname> Roberto</firstname> <surname> Teixeira</surname> +<contrib> Developer</contrib> +<affiliation> <address> <email>roberto@kde.org</email> </address> </affiliation> +</othercredit> + +<othercredit role="developer"> +<firstname> Mathias</firstname> <surname> Waack</surname> +<contrib> Developer</contrib> +<affiliation> <address> <email>mathias@atoll-net.de</email> </address> </affiliation> +</othercredit> + +</authorgroup> + +<copyright> +<year> 2000</year> <year>2001</year> <year>2002</year> +<holder>Stephan Johach</holder> +<holder>Thomas Schütz</holder> +</copyright> + +<date>2002-04-13</date> +<releaseinfo>0.07.00</releaseinfo> + +<!-- Abstract about this handbook --> + +<abstract> +<para>&knode; is an easy-to-use newsreader.</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KNode</keyword> +<keyword>kdenetwork</keyword> +<keyword>newsreader</keyword> +</keywordset> +</bookinfo> + +&introduction; + +<!-- Using chapter is too big to put in one of it's own, so breaking down to sect1 level --> + +<chapter id="using-knode"> +<title>Working with &knode;</title> + +&using-firststart; +&using-subscribing; +&using-morefeatures; +</chapter> + +&commands; + +&faq; + +&journey; + +&more; + +&credits; + +&install; + +&glossary; + +&documentation.index; +</book>
\ No newline at end of file diff --git a/doc/knode/install.docbook b/doc/knode/install.docbook new file mode 100644 index 000000000..6a5f11499 --- /dev/null +++ b/doc/knode/install.docbook @@ -0,0 +1,54 @@ +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-knode"> +<title>Where do I get &knode;?</title> + +&install.intro.documentation; + +</sect1> + +<sect1 id="requirements"> +<title> +Requirements</title> +<anchor id="anc-requirements"/> + +<para>If you want to successfully install &knode;, you need &kde; +3.x; if, in addition, you want to use &knode; as an offline +newsreader, you need a local news server, ⪚ <ulink +url="http://www.leafnode.org"><application>leafnode</application></ulink>.</para> +</sect1> + +<sect1 id="compilation"> +<title>Compile and install</title> + +<para>&knode; is part of the kdenetwork package of &kde; 3.x and is +installed together with it, provided you have chosen to install the +kdenetwork package; so, in general, there is no need for a user +to compile the sources of &knode;.</para> + +&install.compile.documentation; + +</sect1> + +<sect1 id="update-installation"> +<title>Notes about updating an older version of &knode;</title> + +<para>This section contains notes about what to take care of when +installing a newer version of &knode; with an older version already +installed.</para> + +<sect2 id="update-file-changes"> +<title>Changes in configuration files and folders</title> + +<para>Since version 0.2 the format of the configuration files and the +saved articles has changed, so unfortunately, your old configuration +files cannot be imported.</para> + +<para>If you update from a version >= 0.4 the local folders will +automatically be converted into the new format; you will then be +unable to use the data with an older version of &knode; any more.</para> +</sect2> + +</sect1> +</appendix>
\ No newline at end of file diff --git a/doc/knode/introduction.docbook b/doc/knode/introduction.docbook new file mode 100644 index 000000000..a86de4663 --- /dev/null +++ b/doc/knode/introduction.docbook @@ -0,0 +1,56 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd"> --> +<chapter id="introduction"> +<title> Introduction</title> +<anchor id="anc-introduction"/> + +<para>&knode; is an easy-to-use, convenient newsreader; it is intended +to allow even newbies to use a newsreader under &kde;, but it also +offers advanced features appealing to experienced users. &knode; is a +online-reader but could work together with a newsserver like +<application>leafnode</application> as an offline-reader.</para> + +<para>As of version 0.4 &knode; complies with all the requirements of +the <glossterm>GNKSA</glossterm>.</para> + +<para>If you have problems or questions about this program, please +contact the mailing list for &kde; users (for subscription, see<ulink +url="http://www.kde.org/contact.html">Homepage of the &kde; mailing +lists</ulink> ) or one of the &kde; newsgroups:</para> + +<simplelist> +<member>comp.windows.x.kde</member> +<member>de.comp.os.unix.apps.kde (german)</member> +</simplelist> + +<para>If you have found a bug or have suggestions regarding the +functionality of &knode; please report them via the +<menuchoice><guimenu>Help</guimenu><guimenuitem>Report +bug...</guimenuitem></menuchoice> menu.</para> + +<para>Please make sure when asking questions in the newsgroups and +mailing lists mentioned above that the question you are asking +is not answered in this manual.</para> + +<para>For those new to reading news and posting articles, the +<link linkend="knode-journey">A journey through +Usenet</link> chapter is recommended; it is not so much about &knode; as how to +move about in the Usenet with its help. In general, it is not +sufficient to just master a news reader for writing news +articles: imagine a car driver who masters his car perfectly but does +not know about the traffic rules or signs; do you want to encounter +such a driver when out in traffic? So please take your time to learn +at least a little about the <quote>traffic rules</quote> of the +Usenet; the other participants will thank you.</para> + +<tip> +<para>&knode; supports you in many cases with hints and warnings: if +you do not simply ignore them you will avoid many beginners' +mistakes; but, do not exclusively depend on them either.</para> +</tip> + +<para>Please address suggestions and criticisms at the author or at the +responsible translator for your language.</para> + +</chapter> + diff --git a/doc/knode/journey.docbook b/doc/knode/journey.docbook new file mode 100644 index 000000000..30448513f --- /dev/null +++ b/doc/knode/journey.docbook @@ -0,0 +1,530 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd"> --> + +<chapter id="knode-journey"> +<title>A journey in the World of Newsgroups</title> + +<anchor id="anc-knode-journey"/> + +<para>This chapter is supposed to be glance over the World of Newsgroups +and their <quote>inhabitants</quote>; someone who has never dared to go +there before will encounter some strange customs, which may give you a feeling +of being a lonely alien without backup; but stay calm, it is not like +this. The Usenet is a meeting place for all kinds of normal and +not-so-normal folks; it is here where they are distributing a lot of +information but also gossip and other stuff.</para> + +<tip> +<para>References to more detailed and qualified essays on the Usenet +can be found at <link linkend="knode-more-info">More +Resources</link></para> +</tip> + +<sect1 id="about-news"> +<title>What are ...</title> +<anchor id="anc-about-news"/> + +<sect2> +<title>... online-readers?</title> + +<para>An online-reader connects to a newsserver and gives you access to +its content. &knode; is an online-reader: you are reading your News +and publishing your own <glossterm>articles</glossterm> while the +online-reader stays connected.</para> + +</sect2> + +<sect2> +<title>... offline-readers?</title> + +<para>An offline-reader connects to the Server and fetches only the +headers of new articles; then, the connection is closed and you can +mark (offline) the articles you are really interested in. When you +connect next time the offline-reader fetches the articles you +marked and sends the articles you have written whilst offline.</para> + +<para>There is no connection while you are reading or writing +articles.</para> + +</sect2> + +<sect2> +<title>... newsgroups?</title> + +<para>You can look at newsgroups as public bulletin boards and forums, +where everybody is allowed to participate. Articles you have +published in a newsgroup can be read by everybody subscribed to this +newsgroup and, normally, everybody is allowed to publish their articles +in a newsgroup.</para> + +</sect2> + +<sect2> +<title>... news?</title> + +<para>News is the collective term for articles published in a newsgroup.</para> + +</sect2> + +<sect2> +<title>... threads?</title> + +<para>A thread is a topic of discussion in a +newsgroup.</para> + +</sect2> +</sect1> + +<sect1 id="nettiquette"> +<title>Online Manners</title> + +<anchor id="anc-nettiquette"/> + +<para>There are lot of different people meeting and talking in +newsgroups; it is seen as some kind of courtesy to obey some rules of +manner, the basics of which are listed here.</para> + +<orderedlist> +<listitem> +<para>Before you ask questions be sure you have read the newsgroup's +<acronym>FAQ</acronym> (Frequently Asked Questions) and didn't find +the answer.</para> +</listitem> +<listitem> +<para>If you take part in a discussion be aware of the fact that everybody +can read the answer: do not say anything that you would not say to the others +if you were facing them; avoid insults.</para> +</listitem> +<listitem> +<para>Try to avoid crossposting: do not ask a question in more than +one newsgroup when you do not know which is the right one. Ask in one +newsgroup; if it is wrong, you will be told which is right one.</para> +</listitem> +<listitem> +<para>Formulate your articles accurately; nobody likes to read an +article with lots of typos, even with content worth a Pulitzer. Think +of your articles as letters: your letter speaks for you; it represents +you; somebody reading your article will draw conclusions about you +from it, wrong or right.</para> +</listitem> +<listitem> +<para>Remember, nobody sees your grin when you are writing an ironic +sentence: it may be funny for you, but it can be very serious for the +person reading it. It is very difficult to include emotions in an +article.</para> +</listitem> +<listitem> +<para>The most important rule: use your common sense when you are +answering or publishing an article.</para> +</listitem> +</orderedlist> + +</sect1> + +<sect1 id="usenet-slang"> +<title>The Usenet language</title> +<anchor id="anc-usenet-slang"/> + +<para>You will not be surprised about English being the main language on +the Usenet; however, there are special trees for German (de.*), French (fr.*) +and many other languages. If you are unable to determine the main +language of a newsgroup the only possibility is careful listening +or a possible explanation in the description of the group in the +grouplist.</para> + +<para>In addition, over the time the Usenet has developed its own language +but it is easy to learn.</para> + +<sect2> +<title> +<acronym>RTFM</acronym> and other typos</title> + +<para>When you read news, after some time you will read some strange +combinations of letters; for example, you can get a reply like:</para> + +<para>RTFM</para> + +<para>Nothing else. Strange, but absolutely intended; to solve the +riddle: those, most of the time, are shortcuts, acronyms. It is easier +to drop some letters than to write the same sentence over and over +again.</para> + +<para>But what is the meaning of <acronym>RTFM</acronym>? The writer +is asking you to read the manual, documentation or +<acronym>FAQ</acronym> before asking questions in the +newsgroup. It stands for: (R)ead (T)he (F)...ing +(M)anual; <acronym>BTW</acronym> this is advice you should adopt.</para> + +<para>Wait, what is <acronym>BTW</acronym> now? Another often-seen +acronym which means (B)y (T)he (W)ay. It is easy when you know +it; to avoid you having to continuously speculate over the meaning of +acronyms there is table at he end of this section containing the +most-often-used acronyms.</para> + +<para>This table does not try to be complete and is based on a list by +Martin Imlau.</para> + +<table> +<title> +Acronyms on Usenet</title> +<tgroup cols="2"> +<thead> +<row> +<entry> +Acronym</entry> +<entry> +Meaning</entry> +</row> +</thead> +<!--TRANSLATORS: Write the translation in the second column in brackets! --> +<tbody> +<row> +<entry> +<g></entry> +<entry> +grins</entry> +</row> +<row> +<entry> +<acronym> +AAMOF</acronym> +</entry> +<entry> +As a matter of fact</entry> +</row> +<row> +<entry> +<acronym> +ACK</acronym> +</entry> +<entry> +Acknowledge</entry> +</row> +<row> +<entry> +<acronym> +AFAIK</acronym> +</entry> +<entry> +As far as I know</entry> +</row> +<row> +<entry> +<acronym> +AFAIR</acronym> +</entry> +<entry> +As far as I remember</entry> +</row> +<row> +<entry> +<acronym> +AWGTHTGTTA</acronym> +</entry> +<entry> +Are we going to have to go through this again?</entry> +</row> +<row> +<entry> +<acronym> +ASAP</acronym> +</entry> +<entry> +As soon as possible</entry> +</row> +<row> +<entry> +<acronym> +BFN</acronym> +</entry> +<entry> +Bye for now!</entry> +</row> +<row> +<entry> +<acronym> +BTW</acronym> +</entry> +<entry> +By the way</entry> +</row> +<row> +<entry> +<acronym> +BYKT</acronym> +</entry> +<entry> +But you knew that</entry> +</row> +<row> +<entry> +<acronym> +CMIIW</acronym> +</entry> +<entry> +Correct me if I'm wrong</entry> +</row> +<row> +<entry> +<acronym> +CU</acronym> +</entry> +<entry> +See you!</entry> +</row> +<row> +<entry> +<acronym> +CU2</acronym> +</entry> +<entry> +See you too!</entry> +</row> +<row> +<entry> +<acronym> +CYL</acronym> +</entry> +<entry> +See you later!</entry> +</row> +<row> +<entry> +<acronym> +DAU</acronym> +</entry> +<entry> +German abbreviation for the silliest user you can imagine (Dümmster +anzunehmender User)</entry> +</row> +<row> +<entry> +<acronym> +EOD</acronym> +</entry> +<entry> +End of discussion</entry> +</row> +<row> +<entry> +<acronym> +ESOSL</acronym> +</entry> +<entry> +Endless snorts of stupid laughter</entry> +</row> +<row> +<entry> +<acronym> +FYI</acronym> +</entry> +<entry> +For your information</entry> +</row> +<row> +<entry> +<acronym> +GOK</acronym> +</entry> +<entry> +God only knows</entry> +</row> +<row> +<entry> +<acronym> +HAND</acronym> +</entry> +<entry> +Have a nice day!</entry> +</row> +<row> +<entry> +<acronym> +HTH</acronym> +</entry> +<entry> +Hope that helps</entry> +</row> +<row> +<entry> +<acronym> +HSIK</acronym> +</entry> +<entry> +How should I know?</entry> +</row> +<row> +<entry> +<acronym> +IAE</acronym> +</entry> +<entry> +In any event</entry> +</row> +<row> +<entry> +<acronym> +IANAL</acronym> +</entry> +<entry> +I am not a lawyer</entry> +</row> +<row> +<entry> +<acronym> +IIRC</acronym> +</entry> +<entry> +If I remember correctly</entry> +</row> +<row> +<entry> +<acronym> +IMCO</acronym> +</entry> +<entry> +In my considered opinion</entry> +</row> +<row> +<entry> +<acronym> +IMHO</acronym> +</entry> +<entry> +In my humble opinion</entry> +</row> +<row> +<entry> +<acronym> +IMNSHO</acronym> +</entry> +<entry> +In my not so humble opinion</entry> +</row> +<row> +<entry> +<acronym> +INPO</acronym> +</entry> +<entry> +In no particular order</entry> +</row> +<row> +<entry> +<acronym> +IOW</acronym> +</entry> +<entry> +In other words</entry> +</row> +<row> +<entry> +<acronym> +LMAO</acronym> +</entry> +<entry> +Laughing my ass off</entry> +</row> +<row> +<entry> +<acronym> +LOL</acronym> +</entry> +<entry> +Laughing out loudly</entry> +</row> +<row> +<entry> +<acronym> +NAK</acronym> +</entry> +<entry> +Not acknowledged</entry> +</row> +<row> +<entry> +<acronym> +NBD</acronym> +</entry> +<entry> +No big deal</entry> +</row> +<row> +<entry> +<acronym> +NFW</acronym> +</entry> +<entry> +No f...ing way</entry> +</row> +<row> +<entry> +<acronym> +ROTFL</acronym> +</entry> +<entry> +Rolling on the floor, laughing</entry> +</row> +<row> +<entry> +<acronym> +RTFM</acronym> +</entry> +<entry> +Read the f...ing manual</entry> +</row> +<row> +<entry> +<acronym> +SCNR</acronym> +</entry> +<entry> +Sorry, could not resist</entry> +</row> +<row> +<entry> +<acronym> +TIA</acronym> +</entry> +<entry> +Thanks in advance</entry> +</row> +</tbody> +</tgroup> +</table> +</sect2> + +<sect2> +<title>Smile!</title> + +<para>Again, such a strange thing. What is this ;-) meant to be? Turn +your head so the left side of your screen is on top; got it? It's +a smile with a wink? This is a so-called emoticon; emoticons are an +often-used possibility to express emotions, one thing missing in +conversation on the Usenet (but there is a substitute, remember? +;-)</para> + +<para>It is very difficult to express emotions in email or news; your +joking comment appear to be very serious to the recipient and can lead to +unmeant reactions or conflicts (flames); so use emoticons to express +your intention.</para> + +<para>There are a lots of emoticons, which express a great variety of +emotions; the interpretation is easy if you turn your +head and think of a face.</para> + +</sect2> + +<sect2> +<title>PLONK!</title> + +<para>This PLONK! looks like some comic-sound, does it not? And that is +exactly what it is used for. The one who reads it knows he was just +added to the killfile of a newsreader; normally this means the +recipient of the PLONK! annoyed the sender. The PLONK! is meant to +play back the sound of the recipients name hitting the ground in the +<glossterm>killfile</glossterm>.</para> +</sect2> +</sect1> + +</chapter> diff --git a/doc/knode/knode-cleanup.png b/doc/knode/knode-cleanup.png Binary files differnew file mode 100644 index 000000000..9b4a1b051 --- /dev/null +++ b/doc/knode/knode-cleanup.png diff --git a/doc/knode/knode-colors-fonts.png b/doc/knode/knode-colors-fonts.png Binary files differnew file mode 100644 index 000000000..37934238e --- /dev/null +++ b/doc/knode/knode-colors-fonts.png diff --git a/doc/knode/knode-composer-attachments.png b/doc/knode/knode-composer-attachments.png Binary files differnew file mode 100644 index 000000000..dad84a292 --- /dev/null +++ b/doc/knode/knode-composer-attachments.png diff --git a/doc/knode/knode-composer-settings.png b/doc/knode/knode-composer-settings.png Binary files differnew file mode 100644 index 000000000..b4b27a030 --- /dev/null +++ b/doc/knode/knode-composer-settings.png diff --git a/doc/knode/knode-edit-filter.png b/doc/knode/knode-edit-filter.png Binary files differnew file mode 100644 index 000000000..4c0916892 --- /dev/null +++ b/doc/knode/knode-edit-filter.png diff --git a/doc/knode/knode-edit-header1.png b/doc/knode/knode-edit-header1.png Binary files differnew file mode 100644 index 000000000..6b7115050 --- /dev/null +++ b/doc/knode/knode-edit-header1.png diff --git a/doc/knode/knode-edit-header2.png b/doc/knode/knode-edit-header2.png Binary files differnew file mode 100644 index 000000000..b59a665a6 --- /dev/null +++ b/doc/knode/knode-edit-header2.png diff --git a/doc/knode/knode-filters.png b/doc/knode/knode-filters.png Binary files differnew file mode 100644 index 000000000..de4a20bbe --- /dev/null +++ b/doc/knode/knode-filters.png diff --git a/doc/knode/knode-followup.png b/doc/knode/knode-followup.png Binary files differnew file mode 100644 index 000000000..02edf3313 --- /dev/null +++ b/doc/knode/knode-followup.png diff --git a/doc/knode/knode-header-settings.png b/doc/knode/knode-header-settings.png Binary files differnew file mode 100644 index 000000000..35ba241bd --- /dev/null +++ b/doc/knode/knode-header-settings.png diff --git a/doc/knode/knode-identity.png b/doc/knode/knode-identity.png Binary files differnew file mode 100644 index 000000000..e732f264f --- /dev/null +++ b/doc/knode/knode-identity.png diff --git a/doc/knode/knode-mail-account.png b/doc/knode/knode-mail-account.png Binary files differnew file mode 100644 index 000000000..de4458d06 --- /dev/null +++ b/doc/knode/knode-mail-account.png diff --git a/doc/knode/knode-new-article.png b/doc/knode/knode-new-article.png Binary files differnew file mode 100644 index 000000000..3fcc44830 --- /dev/null +++ b/doc/knode/knode-new-article.png diff --git a/doc/knode/knode-news-account.png b/doc/knode/knode-news-account.png Binary files differnew file mode 100644 index 000000000..e2aa1f66c --- /dev/null +++ b/doc/knode/knode-news-account.png diff --git a/doc/knode/knode-post-settings.png b/doc/knode/knode-post-settings.png Binary files differnew file mode 100644 index 000000000..b7301a23d --- /dev/null +++ b/doc/knode/knode-post-settings.png diff --git a/doc/knode/knode-read-news-appearance-dialog.png b/doc/knode/knode-read-news-appearance-dialog.png Binary files differnew file mode 100644 index 000000000..8c98f2622 --- /dev/null +++ b/doc/knode/knode-read-news-appearance-dialog.png diff --git a/doc/knode/knode-read-news-settings.png b/doc/knode/knode-read-news-settings.png Binary files differnew file mode 100644 index 000000000..610b4bd07 --- /dev/null +++ b/doc/knode/knode-read-news-settings.png diff --git a/doc/knode/knode-reply.png b/doc/knode/knode-reply.png Binary files differnew file mode 100644 index 000000000..497007d11 --- /dev/null +++ b/doc/knode/knode-reply.png diff --git a/doc/knode/knode-rule-editor.png b/doc/knode/knode-rule-editor.png Binary files differnew file mode 100644 index 000000000..224e4be3c --- /dev/null +++ b/doc/knode/knode-rule-editor.png diff --git a/doc/knode/knode-search.png b/doc/knode/knode-search.png Binary files differnew file mode 100644 index 000000000..68b28af16 --- /dev/null +++ b/doc/knode/knode-search.png diff --git a/doc/knode/knode-start.png b/doc/knode/knode-start.png Binary files differnew file mode 100644 index 000000000..8d4307fcf --- /dev/null +++ b/doc/knode/knode-start.png diff --git a/doc/knode/knode-subscribe.png b/doc/knode/knode-subscribe.png Binary files differnew file mode 100644 index 000000000..4357ae54a --- /dev/null +++ b/doc/knode/knode-subscribe.png diff --git a/doc/knode/knode-views.png b/doc/knode/knode-views.png Binary files differnew file mode 100644 index 000000000..5fbae986d --- /dev/null +++ b/doc/knode/knode-views.png diff --git a/doc/knode/more.docbook b/doc/knode/more.docbook new file mode 100644 index 000000000..79bab8261 --- /dev/null +++ b/doc/knode/more.docbook @@ -0,0 +1,134 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd"> --> + +<chapter id="knode-more-info"> +<title> +Further Information</title> +<anchor id="anc-knode-more-info"/> +<!-- TRANSLATORS! Please modify this chapter for your language specific needs --> + +<para>In this section we will detail some additional information +resources which could be useful to you. Many of the articles listed +below (for which <acronym>URL</acronym>s are given) are posted to +news groups regularly; some of those groups are also listed +here.</para> + +<sect1 id="infos-newsgroups"> +<title>Informative Newsgroups</title> + +<anchor id="anc-infos-newsgroups"/> +<simplelist> +<member>news.answers</member> +<member>news.newusers.questions</member> +<member>de.newsusers.infos (German)</member> +<member>de.answers (German)</member> +<member>de.comp.os.unix.linux.infos (German)</member> +<member>de.newusers.answers (German)</member> +<member>de.newusers.questions (German)</member> +</simplelist> + +<para>For beginners it is especially recommended to read these +articles at least partially: informed users have strong advantages in +news groups. There are some more-specialized news groups where +<acronym>FAQ</acronym>s and introductory +<glossterm>articles</glossterm> are posted frequently, ⪚ the +<glossterm>newsgroup</glossterm> de.comp.os.unix.linux.infos (German), +which contains a lot of useful articles about the &Linux; operating system. +Just have a look on the group list of your newsserver for +it.</para> + +</sect1> + +<sect1 id="infos-testgroups"> +<title>Test Groups</title> + +<anchor id="anc-infos-testgroups"/> + +<para>The following groups were created especially for testing, +&ie; after successfully configuring &knode; you should post some +articles to those groups to test your settings.</para> + +<para>Some groups support automatic replies through email to enable you to +test whether your entered identity is correct and mail-replies actually +arrive in your mailbox.</para> + +<para>In addition, some scripts are offered which check your articles +for erroneous settings and generate a followup with useful +hints.</para> + +<simplelist> +<member>de.test (German test newsgroup)</member> +<member>misc.test</member> +<member>alt.test</member> +<member>alt.test.ignore</member> +</simplelist> +</sect1> + +<sect1 id="infos-urls"> +<title>Informative technical articles in the world wide web</title> + +<anchor id="anc-infos-urls"/> + +<para>These <acronym>URL</acronym>s are from the corresponding article +in the <glossterm>newsgroup</glossterm> +<emphasis>de.newusers.infos</emphasis> and have the same contents as +the articles posted there.</para> + +<simplelist> +<member>Introduction for de.newusers.infos: <ulink url="http://www.kirchwitz.de/~amk/dni/einleitung">http://www.kirchwitz.de/~amk/dni/einleitung</ulink> +(German)</member> +<member>The newsgroups of the de.alt hierarchy: <ulink url="http://www.kirchwitz.de/~amk/dni/de-alt-newsgruppen"> +http://www.kirchwitz.de/~amk/dni/de-alt-newsgruppen</ulink> +(German)</member> +<member>The newsgroups of the de-hierarchy: <ulink +url="http://www.kirchwitz.de/~amk/dni/de-newsgruppen">http://www.kirchwitz.de/~amk/dni/de-newsgruppen</ulink> +(German)</member> +<member>First read, then post: <ulink +url="http://www.kirchwitz.de/~amk/dni/erst-lesen-dann-schreiben">http://www.kirchwitz.de/~amk/dni/erst-lesen-dann-schreiben</ulink> (German)</member> +<member>First steps in the usenet: <ulink +url="http://www.kirchwitz.de/~amk/dni/erste-schritte">http://www.kirchwitz.de/~amk/dni/erste-schritte</ulink> +(German)</member> +<member>Questions and answers from de.newusers.questions: <ulink +url="http://www.kirchwitz.de/~amk/dni/faq">http://www.kirchwitz.de/~amk/dni/faq</ulink> +(German)</member> +<member>Seven theses about behavior in the internet: <ulink +url="http://www.kirchwitz.de/~amk/dni/hoeflichkeit">http://www.kirchwitz.de/~amk/dni/hoeflichkeit</ulink> +(German)</member> +<member>Introduction to the usenet: <ulink +url="http://www.kirchwitz.de/~amk/dni/usenet-einfuehrung">http://www.kirchwitz.de/~amk/dni/usenet-einfuehrung</ulink> +(German)</member> +<member>Why should I take the rules seriously? <ulink +url="http://www.kirchwitz.de/~amk/dni/warum-regel">http://www.kirchwitz.de/~amk/dni/warum-regel</ulink> +(German)</member> +<member>The newsreader <acronym>FAQ</acronym>: <ulink +url="http://www.crosswinds.net/~cgarbers/faq/newsreaderFAQ.htm">http://www.crosswinds.net/~cgarbers/faq/newsreaderFAQ.htm</ulink></member> +<member>The correct quoting: <ulink +url="http://www.afaik.de/usenet/faq/zitieren">http://www.afaik.de/usenet/faq/zitieren</ulink> +(German)</member> +<member>The German umlauts <acronym>FAQ</acronym>: <ulink +url="http://www.westfalen.de/paefken/de.newusers/umlaute-faq.txt"> +http://www.westfalen.de/paefken/de.newusers/umlaute-faq.txt</ulink> (German)</member> +</simplelist> +</sect1> + +<sect1 id="infos-technical"> +<title>Informative technical articles</title> +<anchor id="anc-infos-technical"/> + +<para>If you are interested in further technical information in +connection to news, you should not miss the following +<acronym>URL</acronym>s.</para> + +<simplelist> +<member>Header entries: <ulink url="http://www.kirchwitz.de/~amk/dni/headerzeilen"> +http://www.kirchwitz.de/~amk/dni/headerzeilen</ulink> (German)</member> +<member>A very useful message-ID <acronym>FAQ</acronym>: <ulink url="http://www.qad.org/faq/faq-messageid.html"> +http://www.qad.org/faq/faq-messageid.html</ulink></member> +<member>A lot of links about newsreaders and related topics: <ulink +url="http://www.leafnode.org/links">http://www.leafnode.org/links</ulink></member> +<member><acronym>RFC</acronym>s, Drafts and documents for the technical +interested: <ulink url="http://www.landfield.com/usefor/"> +http://www.landfield.com/usefor/</ulink></member> +</simplelist> +</sect1> +</chapter> diff --git a/doc/knode/newsubs.png b/doc/knode/newsubs.png Binary files differnew file mode 100644 index 000000000..ca443d01e --- /dev/null +++ b/doc/knode/newsubs.png diff --git a/doc/knode/redball.png b/doc/knode/redball.png Binary files differnew file mode 100644 index 000000000..506343729 --- /dev/null +++ b/doc/knode/redball.png diff --git a/doc/knode/redballchk.png b/doc/knode/redballchk.png Binary files differnew file mode 100644 index 000000000..d84cec9ac --- /dev/null +++ b/doc/knode/redballchk.png diff --git a/doc/knode/using-firststart.docbook b/doc/knode/using-firststart.docbook new file mode 100644 index 000000000..945b26fd2 --- /dev/null +++ b/doc/knode/using-firststart.docbook @@ -0,0 +1,1859 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE sect1 PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" +"dtd/kdex.dtd"> --> +<sect1 id="first-start"> +<title>The first start</title> + +<para>You can find &knode; in the <guimenu>K</guimenu> Menu under the +<guisubmenu>Internet</guisubmenu> entry: the menu entry +<guimenuitem>KNode</guimenuitem> launches the program.</para> + +<tip> +<para>If the entry for &knode; can not be found or if &knode; does +not appear after clicking on the menu entry, read <link +linkend="faq">Questions and Answers</link>.</para> +</tip> + +<para>The main window of &knode; should now be displayed on your +desktop as shown; on the first start, the settings dialog will be +invoked.</para> + +<screenshot> +<screeninfo>Setting up &knode;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-start.png" format="PNG"/></imageobject> +<textobject> +<phrase>&knode; after first start</phrase> +</textobject> +<caption> +<para>&knode; after first start</para> +</caption> +</mediaobject> +</screenshot> + +<para>The windows shows the menu bar, the toolbar below and the status +pane at the buttom. The area between the toolbar and the status pane +is occupied by a three-part window.</para> + +<para>There is a folder view, which currently contains only three +entries:</para> + +<simplelist> +<member>The folder <guilabel>Outbox</guilabel></member> +<member>The folder <guilabel>Drafts</guilabel></member> +<member>The folder <guilabel>Sent</guilabel></member> +</simplelist> + +<para>When &knode; is completely and correctly configured, the news +servers and the subscribed news groups will appear there.</para> + +<para>In the upper section is the article view; it is currently empty +and does not show any articles. Directly below the article view is the +article window; the body of the currently-selected article +appears there. These windows are also blank at the moment, as there +are no articles, of course. You should not be concerned, though, as before +reading and publishing news some things have to be configured; this +will be covered by the following section.</para> + +<para>We are now beginning the setting up of &knode;. Most settings +are not important for daily use, but you should know what settings are +possible and what they are for. Some may skip the +<quote>Quickstart</quote> chapter but those who prefer a quick start +will just glance over the manual anyway. For others, especially those +who have not any or much experience with a news reader, this chapter +offers the chance to fully perform the configuration, although some +things may become clear only later on.</para> + +<sect2 id="setting-your-identity"> +<title>Personal settings</title> + +<anchor id="anc-setting-your-identity"/> + +<para>Via +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode...</guimenuitem></menuchoice> you will enter the preferences +dialog of &knode;. The figure shows the dialog.</para> + +<screenshot> +<screeninfo>Dialog for entering personal information</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-identity.png" format="PNG"/></imageobject> +<textobject> +<phrase>Entering personal information</phrase> +</textobject> +<caption> +<para>Entering personal information</para></caption> +</mediaobject> +</screenshot> + +<para>The dialog is divided into two parts: in one part there is a treeview, in +which the top entry <guilabel>Identity</guilabel> is already +highlighted; in the other part is the corresponding input +dialog -- these settings relate to the identity with which you navigate +through the newsgroups.</para> + +<tip> +<para>If you have already configured your personal settings in the +&kcontrolcenter; before the first start of &knode;, they will be +adopted.</para> +</tip> + +<sect3> +<title><guilabel>Name</guilabel></title> + +<para>In the field <guilabel>Name</guilabel> you enter your name, ⪚ +<replaceable>Joe Miller</replaceable> or <replaceable>Mary +Gordon</replaceable>. This name will later appear in the newsgroups as +sender, and can be seen by anyone.</para> + +<para>Filling out the field <guilabel>Name</guilabel> is +mandatory.</para> + +<caution> +<para> +In most newsgroups, it is considered polite and appropriate to appear +with one's real name; other newsgroups are less strict about this. But, +there are also cases when one would not want to appear with one's real +name, ⪚ in newsgroups where one would like to (and can) talk about +very personal matters without being exposed; these groups mostly do +tell you in their Charter that the anonymity of their members is +explicitly approved.</para> +</caution> + +<tip> +<para>For those special cases, &knode; offers settings that can be +adjusted to each newsgroup individually; further information can be +found under <link linkend="group-identity">Group local +Identities</link>.</para> +</tip> +</sect3> + +<sect3> +<title><guilabel>Organization</guilabel></title> + +<para>The input field <guilabel>Organization</guilabel> is optional +and does not have to be filled out. You can enter, ⪚, the name of +your company or your university if you use &knode; +there; if you leave this field blank, it will often be filled out +later by your Internet service provider.</para> +</sect3> + +<sect3> +<title><guilabel>Email address</guilabel></title> + +<para>The email address you enter here will be used as sender in news +articles, &ie; as actual address of the author, in conjunction with +the real name (set in the field <guilabel>Name</guilabel>).</para> + +<para>The field <guilabel>Email Address</guilabel> shows up when +someone wants to reply to you by email: the email will be sent to +the address entered here. Many newsreaders display the sender address +together with the name in the Header of the article.</para> + +<para>Filling out the <guilabel>Email Address</guilabel> field is +mandatory.</para> +<tip> +<para>Note that the e-mail address will only be used for replies to you if +the field <guilabel>Reply-to Address</guilabel> is not filled out; in +this case, the field <guilabel>Email</guilabel> will be ignored for +replies and the address given under <guilabel>Reply-to +Address</guilabel> will be used.</para> +</tip> +</sect3> + +<sect3> +<title><guilabel>Reply-to Address</guilabel></title> + +<para><guilabel>Reply-to Address</guilabel> offers you the possibility +to enter a different address than your sender e-mail address: if +someone replies to you by email this address will be displayed as +target address in the reply. An example for using <guilabel>Reply-to +Address</guilabel> would be that you write the article at the office +during the day but want to receive the answer in your home inbox, +because your boss co-reads your mail.</para> + +<para>Only enter an e-mail address in that field if it actually +differs from the field <guilabel>Email Address</guilabel>.</para> + +<warning> +<para>Some news readers deliberately set this to an invalid e-mail +address in order to prevent spam mails from being received; what could +happen, though, is that a reader sends an e-mail to this invalid address +which you will therefore never receive. You should drop a note about +this in the signature.</para> +</warning> +</sect3> + +<sect3> +<title><guilabel>Mail-Copies-To</guilabel></title> + +<para>If you enter an email address here every article will be sent +to the usenet and to this email address.</para> +</sect3> + +<sect3> +<title><guilabel>Signing Key</guilabel></title> + +<para>If you have configured the use of <acronym>PGP</acronym> or +GnuPG you can chose your signing key with +<guibutton>Change...</guibutton>. </para> +</sect3> + +<sect3> +<title><guilabel>Use a signature from file</guilabel></title> + +<para>If this option is selected, the file specified under +<guilabel>Signature File</guilabel> will be used as Signature.</para> +</sect3> + +<sect3> +<title><guilabel>Signature File</guilabel></title> + +<para>The field <guilabel>Signature File</guilabel> determines the +file, the content of which is appended to each of your articles. The +field is only enabled if the option <guilabel>Use a signature from +file</guilabel> is selected.</para> + +<para>The signature file is a simple text file, which should not +contain more than four lines; it can, for example, contain a reference +to your homepage with the corresponding link, your postal address with +your telephone number (which would then be of course visible to the +whole world with every article) or just a cool quote. The signature is +your brand, so to speak, which will mark all your articles; therefore, +your signature should not be designed sloppily or in the long run annoying +to others: an old joke that one would have to read over and over again +does not foster sympathy or the interest of the other newsgroup +subscribers.</para> + +<para>You can directly enter the file name of the signature file but +it is more convenient to use the button +<guibutton>Choose...</guibutton>. This opens a file open dialog and +you can conveniently choose the signature file with the mouse. The +button <guibutton>Edit File</guibutton> enables you, after choosing +the file, to edit the signature.</para> + +<tip> +<para>It is not necessary to include a separation line in the +signature file as &knode; inserts it automatically.</para> +</tip> +</sect3> + +<sect3> +<title><guilabel>The file is a program</guilabel></title> + +<para>If this option is activated, the signature file is not handled +as a text file, but as a program. The signature file will be started +as a program and the output will be used as a signature. Through that +you'll be able to chose a signature by accident or to use fortune to +generate a cool slogan every time.</para> + +</sect3> + +<sect3> +<title><guilabel>Specify signature below</guilabel></title> + +<para>If this option is selected you can enter the text of the +signature directly in the input field below.</para> + +<tip> +<para>Please make sure that in this case also your +<glossterm>signature</glossterm> should not contain more than 4 +lines. A separation line is not necessary as &knode; inserts it +automatically.</para> +</tip> +</sect3> + +<sect3> +<title>General notes</title> + +<para>You can later adapt the identity individually for each of the +subscribed groups via the <guilabel>Preferences</guilabel> dialog, +⪚ you can specify an English signature for English groups and a +German one for German groups. Apart from the language it is also +possible to have context-sensitive signatures, ⪚ your favorite +recipe in a cooking group or the names of your twelve cats in a cat +owner group.</para> + +<para>You find more in the section <link +linkend="group-identity">Group local identities</link>.</para> + +<para>The next step in the configuration covers the news +account.</para> + +</sect3> +</sect2> + +<sect2 id="setting-the-news-account"> +<title>Configuring the news account</title> +<anchor id="anc-setting-the-news-account"/> + +<para>Now we must tell &knode; about where we get the news from or +where to send the articles to later on. In the tree view on the +right, there is an <guilabel>Accounts</guilabel> entry; click on it +with the mouse; then, two sub entries will be opened out. Choose the +<guilabel>News</guilabel> entry, because we first want to configure +the news account: the list of accounts is still empty.</para> + +<para>To create a new account click on <guibutton>New...</guibutton>. The +following dialog appears:</para> + +<screenshot> +<screeninfo>The <guilabel>New Account</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-news-account.png" format="PNG"/></imageobject> +<textobject> +<phrase>The <guilabel>New Account</guilabel> dialog</phrase> +</textobject> +<caption> +<para>The <guilabel>New Account</guilabel> dialog</para> +</caption> +</mediaobject> +</screenshot> + +<sect3> +<title><guilabel>Name</guilabel></title> + +<para>The <guilabel>Name</guilabel> field can be filled in as you +like; the text you enter will later be visible in the folder view. You +could, for example, enter the name of your Internet Provider; for our example we +enter the name <userinput>My News Account</userinput>.</para> + +</sect3> + +<sect3> +<title><guilabel>Server</guilabel></title> + +<para>The next field is labelled <guilabel>Server</guilabel>. Unlike +the field <guilabel>Name</guilabel>, what you enter here is +important. The name of the news server is fixed and you should be able +to get it from your Internet service provider; if you do not know the name +of the news server, you should get it now: without this information you can +not read any news. If your Internet service provider doesn't own a +news server you can use a public one (universities often provide public news +servers.)</para> + +<para>For our example configuration we enter the name +<userinput><systemitem +class="systemname">news.server.com</systemitem></userinput>; you will, +of course, enter the real name of your news server.</para> + +<tip> +<para>If you want to use &knode; with a local news server, enter the name +<userinput><systemitem +class="systemname">localhost</systemitem></userinput> here.</para> +</tip> +</sect3> + +<sect3> +<title><guilabel>Port</guilabel></title> + +<para><guilabel>Port</guilabel>, the next field, has already a default +value. The Port designates, roughly speaking, a data channel on which +the server listens for whether someone wants to retrieve news: it +defaults to the value 119, which is applicable in most +cases; therefore, we do not change this default for our example.</para> +</sect3> + +<sect3> +<title><guilabel>Hold connection for</guilabel></title> + +<para>The time value you enter here is used if you have +established a connection to the news server and if, for whatever +reason, no data is received from or transmitted to the news +server: after the specified time has elapsed &knode; will automatically +disconnect. This, amongst other things, relieves the server of +unnecessary connections which would otherwise reduce its availability +for other subscribers; it also makes sure that an automatically-established +Internet connection is not held unnecessarily even if no data is +being sent or received.</para> + +<tip> +<para>This settings mainly makes sense if one receives and reads +news online; for local news servers it is of almost no importance. If +this waiting time is set too low, there can be waiting periods if you +read a longer article and do not do <quote>anything</quote> for some +time: &knode; will have canceled the connection to the server by then (after +the time period has elapsed) and has to reestablish it, causing a delay.</para> +<para> If the waiting time is set too high you might waste online +time whilst doing nothing (perhaps increasing your phone bill).</para></tip> +</sect3> + +<sect3> +<title><guilabel>Timeout</guilabel></title> + +<para>If &knode; connects to the news server it waits no longer than the +time specified here for an answer; if the period is exceeded &knode; cancels +the connection attempt and you will get an error message stating that the +server is not responding.</para> + +<tip> +<para>Depending on the quality of your Internet account and the +news server's current load there can be busy periods where +&knode; cancels the connection; if this happens frequently, you should +set this setting to a higher value.</para> +</tip> +</sect3> + +<sect3> +<title> +<guilabel>Fetch group descriptions</guilabel></title> + +<para>If this setting is selected, &knode; additionally requests the +available group descriptions; they will be displayed in the +<guilabel>Subscribe to Newsgroups</guilabel> dialog.</para> + +<tip> +<para>There is not a group description for every group, so it is not +an error if no group description is shown when subscribing to a group +later on.</para> +</tip> + +</sect3> + +<sect3> +<title><guilabel>Server requires authentication</guilabel></title> + +<para>The option <guilabel>Server requires authentication</guilabel> +needs only to be selected if your news server requires a user name and +a password when retrieving articles; you can find out if this is the case +from your Internet service provider or the server's +maintainer.</para> + +<tip> +<para>If you do not know if this setting is necessary forget +about selecting it for now: if you encounter an error later on, you can +try selecting it then. Otherwise, select this option and enter your user name +under <guilabel>User</guilabel> and the associated password +under <guilabel>Password</guilabel>.</para> +</tip> +</sect3> + +<sect3> +<title>General notes</title> + +<para>By now you have completed the setup of your news account. You can +confirm and save your settings by clicking on the +<guibutton>OK</guibutton> button: as soon as you have done that, +the account will appear in the list by the name that you entered in +<guilabel>Name</guilabel> earlier; and, if you have a close look, you +will see that the account also appears in the folder view.</para> + +<para>Using the <guibutton>Subscribe</guibutton> button you could +get directly to the dialog for subscribing to news groups; but, we +still have more to do so we'll ignore it for now: there are several ways +that lead to the goal.</para> + +<para>In the <link linkend="multiple-news-accounts"> Managing +multiple news accounts</link> chapter you can learn how to work with multiple +news accounts, but first we will stay with this one; in most cases, +one account is sufficient.</para> + +<caution> +<para>Please note that some Internet providers only allow retrieving +news from their news server if you are connected to the Internet +through them.</para> +</caution> + +<para>We will now move on to configuring the email account; in order +to do that, click on the <guilabel>Mail</guilabel> entry in the tree +view on the left.</para> + +</sect3> +</sect2> + +<sect2 id="setting-the-mail-account"> +<title>Setting up the mail account</title> + +<para>After selecting <guilabel>Mail</guilabel> in the tree view, the +following dialog box appears.</para> + +<screenshot> +<screeninfo>Dialog box for setting up the mail account</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-mail-account.png" format="PNG"/></imageobject> +<textobject> +<phrase>Setting up the mail account</phrase> +</textobject> +<caption> +<para>Setting up the mail account</para> +</caption> +</mediaobject> +</screenshot> + +<para>You will notice this dialog box is very similar to the news +account settings dialog box; but why do we need an email account in a +newsreader?</para> + +<para>Sometimes you need to answer to the author of an article +directly, without posting to the newsgroup; for example, when you want +to make a very personal comment or want to correct an error. Sometimes +an email is more appropriate than a public remark.</para> + +<para>That's why &knode; provides the possibility to reply by +email; if you want to use this feature you must tell &knode; how to +send emails: you just need to insert the mail server's address. If you have +already configured an email account, ⪚ with &kmail;, you can reuse +the settings used there.</para> + +<sect3> +<title><guilabel>Use external mail program</guilabel></title> + +<para>If this option is active &knode; will use the mail program +which is configured in the control center; the other options in this +dialog will then be disabled.</para> + +</sect3> + +<sect3> +<title><guilabel>Server</guilabel></title> + +<para>The name (address) of your mail server as provided by your Internet +service +provider or system administrator; all you have to do here is enter the mail +server's +name in the <guilabel>Server</guilabel> field.</para> + +<para>In our example we enter<userinput><systemitem +class="systemname">mail.server.de</systemitem></userinput></para> + +<tip> +<para>If you have one you can send your mail via a local mail +server; if this is the case local mail server enter <systemitem +class="systemname">localhost</systemitem> in the +<guilabel>Server</guilabel> field.</para> +</tip> +</sect3> + +<sect3> +<title><guilabel>Port</guilabel></title> + +<para>Again, the <guilabel>Port</guilabel> field has a default +value; in this case it's port 25. You should not need to change this, +unless your <acronym>ISP</acronym> has a very exotic configuration +and tells you to do so. We do not change this for the example.</para> + +</sect3> + +<sect3> +<title>Hold connection for</title> + +<para>This value is important: if you have established a connection +with your mail server and there is no data transfer occurring &knode; +cancels the connection to your mailserver after the specified amount +of time has elapsed.</para> + +</sect3> + +<sect3> +<title><guilabel>Timeout</guilabel></title> + +<para>When &knode; tries to connect to the mail server it will wait this +long for a reply from the server; if this time is exceeded, you will get a +error message.</para> + +<tip> +<para>Depending on the quality of your connection and the actual load +of your mail server you might get long reply times; if &knode; cancels +the connection due to this, you should increase the timeout.</para> +</tip> +</sect3> + +<sect3> +<title>General notes</title> + +<caution> +<para>Some <acronym>ISP</acronym>s only allow you to send email using +their mail server after you have checked your mailbox for new mail: this +reduces spamming.</para> + +<para>For the same reasons, some <acronym>ISP</acronym>s will only allow you +to send mail using their mailservers if you are online with them +or if you are logged in at the mailserver; for example, this is the normal +configuration at GMX and isn't supported by &knode; or &kmail; yet.</para> +</caution> + +</sect3> +</sect2> + +<sect2 id="knode-appearance"> +<title>Defining the appearance</title> + +<para>With the <guilabel>Appearance</guilabel> dialog you are given +the ability to set the colors, the character code and the font size of +the text in the article window; the picture below shows the +dialog.</para> + +<screenshot> +<screeninfo>Setting up the Appearance dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-colors-fonts.png" format="PNG"/></imageobject> +<textobject> +<phrase>Setting up the Appearance dialog</phrase> +</textobject> +<caption> +<para>Setting up the Appearance dialog</para> +</caption> +</mediaobject> +</screenshot> + +<sect3> +<title><guilabel>Use custom colors</guilabel></title> + +<para>If you select this option you can adjust the color settings of +&knode; in the list field below; to change a color setting do a +double-click with the &LMB; on the list entry to open the &kde; +color-selection dialog.</para> + +<para>The color selection can only be configured after the checkbox +has been checked; otherwise, a double-click on the list entries +won't do anything.</para> + +<caution> +<para>If the <guilabel>Use custom colors</guilabel> setting is +selected &knode; won't use colors which have been changed later +globally for &kde; but will only use the colors defined here +instead.</para> +</caution> +</sect3> + +<sect3> +<title><guilabel>Use custom fonts</guilabel></title> + +<para>If you select this setting you can adjust the fonts which +&knode; uses for the display in the list field below; to choose a +font do a double-click with the &LMB; on the list entry to open the +&kde; font-selection dialog.</para> + +<para>The font can only be configured after the checkbox has been +checked; otherwise, a double click on the list entries won't do +anything.</para> + +<caution> +<para>If the setting <guilabel>Use custom fonts</guilabel> is +selected &knode; won't use later changes to the global font settings +for &kde; but will use the fonts defined here instead.</para> +</caution> +</sect3> + +</sect2> + +<sect2 id="setting-news-general"> +<title>General News Settings</title> + +<para>Now click on <guibutton>Reading news</guibutton> and then on the +<guibutton>General</guibutton> sub-entry; the figure below shows the dialog +containing the preferences you can configure there.</para> + +<screenshot> +<screeninfo><guilabel>General Preferences</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-read-news-settings.png" format="PNG"/></imageobject> +<textobject> +<phrase>The <guilabel>General Preferences</guilabel> dialog</phrase> +</textobject> +<caption> +<para>The <guilabel>General Preferences</guilabel> dialog</para> +</caption> +</mediaobject> +</screenshot> + +<para>You don't need to change most of these settings, but we will +discuss them step-by-step to give you an overview of the +possibilities of &knode;.</para> + +<sect3> +<title><guilabel>Check for new articles +automatically</guilabel></title> + +<para>If this box is checked &knode; tries to request new articles +from the server when selecting a newsgroup. These settings especially +make sense when you use &knode; together with a local news +server: downloading the messages obviously only works when the server +is reachable; for a server which is only reachable via an Internet +connection, this setting rarely makes sense and should stay +deactivated.</para> + +<para>If your system isn't set up to establish an Internet connection +if necessary, you will get an error message each time you select a +newsgroup.</para> + +<para>If you want to keep control over when a connection to the server +is established, the +<menuchoice><guimenu>Group</guimenu><guimenuitem>Get new +articles</guimenuitem></menuchoice> menu option is appropriate.</para> + +</sect3> + +<sect3> +<title><guilabel>Maximal number of articles to fetch</guilabel></title> + +<para>This sets a restriction on the number articles which are requested +from the server while downloading. The value configured here is for +each newsgroup separately. If this is set, for instance, to 300 only +the 300 newest articles of the newsgroup are requested; other articles will +be discarded.</para> + +<warning> +<para>For newsgroups with relatively high traffic you might lose +articles if this value is too low; this especially occurs when you've +just subscribed to a newsgroup or only occasionally download articles +and the traffic for this reason rises above the value specified +here.</para> +</warning> +</sect3> + +<sect3> +<title><guilabel>Mark article as read after</guilabel></title> + +<para>Articles you have opened in the article window are marked as +read after the number of seconds specified here. If you set this value +to be relatively high you avoid articles you have just glanced at +being marked as read; on the other hand, it can be annoying for +relatively short articles, for which you need less time to read than +specified: if you browsed too quickly through the articles +they would stay unread even though you have read them. Therefore, you +should adjust this value to your personal preferences.</para> + +</sect3> + +<sect3> +<title><guilabel>Mark crossposted articles as read</guilabel></title> + +<para>Sometimes an <glossterm>article</glossterm> will be posted to +more than one group; this is known as crossposting. If you activate this +option, those crossposted articles will be marked as read in all the +newsgroups to which they were posted if you read it in one newsgroup.</para> + +</sect3> + +<sect3> +<title><guilabel>Smart scrolling</guilabel></title> + +<para>If this option is selected the lines in the article list are +scrolled smoothly instead of jerkily. +</para> <!-- LW: FIXME could be explained a tiny bit better --> + +</sect3> + +<sect3> +<title><guilabel>Show whole thread on expanding</guilabel></title> + +<para>This setting lets a discussion be displayed completely (over +multiple answer levels) if you click on the plus in front of the +discussion; if this setting isn't checked, only the immediate answers +to the current article are displayed.</para> + +</sect3> + +<sect3> +<title><guilabel>Default to expanded threads</guilabel></title> + +<para>Here you can toggle whether the threads are expanded by default or +not.</para> + +</sect3> + +<sect3> +<title><guilabel>Show article score</guilabel></title> + +<para>Here you can toggle whether the scoring column should be shown +in the article view.</para> + +</sect3> + +<sect3> +<title><guilabel>Show line count</guilabel></title> + +<para>Here you can toggle whether the column with the number of lines +should be shown in the article view.</para> + +</sect3> + +<sect3> +<title><guilabel>Cache size for headers</guilabel></title> + +<para>Here you can configure how much memory &knode; should use for +the caching of the headers.</para> + +</sect3> + +<sect3> +<title><guilabel>Cache size for articles</guilabel></title> + +<para>Here you can configure, how much memory &knode; should use for +the caching of the articles.</para> + +</sect3> +</sect2> + +<sect2> +<title><guilabel>Navigation</guilabel></title> + +<para>Here you can change some navigation properties of &knode;. +Normally everything here is switched off, but if you don't like this +kind of navigation you can change it.</para> + +<sect3> +<title><guilabel>General</guilabel></title> + +<para>The keyboard behavior between &knode; and &kmail; is a bit +different; with the <guilabel>Emulate the keyboard behavior of +KMail</guilabel> switch you can activate the same keyboard behavior +as in &kmail; for &knode;.</para> + +</sect3> + +<sect3> +<title><guilabel>Mark All as Read</guilabel></title> + +<para>If the box <guilabel>Switch to next group</guilabel> is checked, +&knode; automatically switches to the next group if you mark all +articles as read.</para> +</sect3> + +<sect3> +<title><guilabel>Mark Thread as Read</guilabel></title> + +<para>If <guilabel>Close the current thread</guilabel> is +checked, &knode; automatically closes a thread if you mark +it as read.</para> + +<para>If <guilabel>Go to next unread thread</guilabel> is +checked, &knode; automatically shows the next thread if you mark the +the previous thread as read.</para> + +</sect3> + +<sect3> +<title><guilabel>Ignore Thread</guilabel></title> + +<para>If <guilabel>Close the current thread</guilabel>is +checked, &knode; automatically closes a thread if you choose to +ignore it.</para> + +<para>If <guilabel>Go to next unread thread</guilabel> is +checked, &knode; automatically shows the next thread if you choose +to ignore the previous one.</para> + +</sect3> +</sect2> + +<sect2 id="knode-scoring-settings"> +<title>Scoring rules</title> + +<para>To sort the articles you have the possibility to score them. The +standard score is 0: a higher score means that the +<glossterm>article</glossterm> is interesting; a lower score means +it is less interesting.</para> + +<para>In the middle of the window you see a big, white area; here you +can see your scoring rules. Scoring rules are used by &knode; to score +the incoming articles automatically; if, for example, a person always +posts nonsense you can automatically score the articles of that person +down and hide them.</para> + +<para>With the buttons below the list of scoring-rules you can +<guibutton>edit</guibutton>, <guibutton>add</guibutton>, +<guibutton>remove</guibutton> and <guibutton>copy</guibutton> a +rule. We will skip this feature for now, because it is not essential +for the setup of &knode;.</para> + +<para>You can learn more about scoring; in the chapter <link +linkend="anc-score-watch-ignore">Scoring, watching and +ignoring</link>.</para> + +<sect3> +<title><guilabel>Default score for ignored threads</guilabel></title> + +<para>Normally you only need the functions ignore and watch; this +simply shows if a thread is interesting or not. Here you can configure +a default score for the ignored threads; choosing the +<menuchoice><guimenu>Scoring</guimenu><guimenuitem>Ignore +Thread</guimenuitem></menuchoice> menu item will give this score to all the +posts in that thread, and will apply that score also to future posts +that follow up the thread.</para> + +</sect3> + +<sect3> +<title><guilabel>Default score for watched threads</guilabel></title> + +<para>If an article is interesting, it will get a score above 0. Here +you can enter the default score for those articles; choosing the +<menuchoice><guimenu>Scoring</guimenu><guimenuitem>Watch +Thread</guimenuitem></menuchoice> menu item will give this score to all the +posts in that thread, and will apply that score also to future posts +that follow up the thread.</para> + +<tip> +<para>You can use the <keycap>W</keycap> key to watch a thread or the +<keycap>I</keycap> key to ignore it.</para> +</tip> +</sect3> +</sect2> + +<sect2 id="knode-filter-settings"> +<title>Filter settings</title> + +<para>This screenshot shows the filter settings.</para> + +<screenshot> +<screeninfo>The filter settings</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-filters.png" format="PNG"/></imageobject> +<textobject> +<phrase>The filter settings</phrase> +</textobject> +<caption> +<para>The filter settings</para> +</caption> +</mediaobject> +</screenshot> + +<para>This dialog shows two lists. The upper list, labeled <guilabel> +Filters</guilabel>, shows all defined filters; when you use &knode; +for the first time, you will only see the predefined filters.</para> + +<para>With the buttons <guibutton>Add</guibutton>, +<guibutton>Delete</guibutton>, <guibutton>Edit</guibutton> and +<guibutton>Copy</guibutton> you can add new filters or delete filters +which are no longer needed; we will skip this feature for now, because +it is not essential for the setup of &knode;.</para> + +<para>You can find more-detailed information about filters in <link +linkend="using-filters">Defining and using filters</link>.</para> + +<para>The lower list, labeled <guilabel>Menu</guilabel>, shows the +appearance of the <menuchoice><guimenu>View</guimenu> +<guisubmenu>Filter</guisubmenu></menuchoice> menu, which you can reach from +the menu bar; the order of the filters in the this menu can be +configured in this list.</para> + +<para>The <guibutton>Up</guibutton> button shifts the selected filter +one position up. Try it: select the second filter and press +<guibutton>Up</guibutton>; this entry will then go up one position.</para> + +<para>The <guibutton>Down</guibutton> button does the opposite +action: select the filter you just shifted one up and +press<guibutton>Down</guibutton> until it reaches its old +position.</para> + +<para>With the two buttons <guibutton>Add Separator</guibutton> and +<guibutton>Remove Separator</guibutton> you can visually group +the filters on the menu. The separators are shown as <literal>====</literal> +in the list; in the Menu they show up as some more-appealing +horizontal lines. Try adding separator; then, select the +separator and remove it by pressing <guibutton>Remove +separator</guibutton>.</para> + +<para>Any changes you make here, you can see in +<menuchoice><guimenu>View</guimenu><guisubmenu>Filter</guisubmenu></menuchoice> +after closing this dialog.</para> + +</sect2> + +<sect2 id="knode-headers"> +<title><guilabel>Customize displayed article headers</guilabel></title> + +<anchor id="anc-knode-headers"/> + +<para>In this dialog you can set how the single header lines are +displayed in the article window.</para> + +<screenshot> +<screeninfo>The <guilabel>Customize displayed article +headers</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-header-settings.png" format="PNG"/></imageobject> +<textobject> +<phrase>The <guilabel>Customize displayed article +headers</guilabel> dialog</phrase> +</textobject> +<caption> +<para>The <guilabel>Customize displayed article +headers</guilabel> dialog</para> +</caption> +</mediaobject> +</screenshot> + +<para>This list shows all the header lines which are to be +display in the article window. The identifiers at the left will be +displayed alongside the header lines in < > to their right; +the header lines are taken from each message, ⪚ for +<guilabel>From</guilabel> the From header line will be used (indicating +who send the message).</para> + +<para>Using <guibutton>Edit</guibutton> you can alter the shown +identifiers, alter the header line shown by each identifier and +change the font settings of the text used. To make things clearer, +we'll now simply select the +<guilabel>From:<From></guilabel> entry in the list and open the dialog +for editing the header display by clicking on +<guibutton>Edit</guibutton>.</para> + +<screenshot> +<screeninfo>The Header Properties dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-edit-header1.png" format="PNG"/></imageobject> +<textobject> +<phrase>The Header Properties dialog</phrase> +</textobject> +<caption> +<para>The Header Properties dialog</para> +</caption> +</mediaobject> +</screenshot> + +<sect3> +<title><guilabel>Header</guilabel></title> + +<para>The <guilabel>Header</guilabel> selection box shows the entry +<guilabel>From</guilabel>: that is the name of the header line for the +sender, as present in the article and evaluated by the +newsreader. If you drop down the selection box &knode; shows a range +of other identifiers, which stand all for a certain header lines in the +article: for now, we'll leave the <guilabel>From</guilabel> identifier +configured; we'll work with this list later, when we add a header line +to the display.</para> +</sect3> + +<sect3> +<title><guilabel>Displayed Name</guilabel></title> + +<para>This field holds the name you'd like to be later shown in the article +window as a label alongside the actual header +line text; for example, for the <guilabel>From</guilabel> header line the +label <guilabel>From</guilabel> is used. If you leave this field blank, only the +content of the header line appears in the article window; this is, for +example, the default setting for the <guilabel>Subject</guilabel> +header line. We won't change anything here either, for now.</para> + +</sect3> + +<sect3> +<title><guilabel>Name</guilabel></title> + +<para>Here you can influence the way the 'Displayed Name' +text is displayed; in our case, the <guilabel>Bold</guilabel> attribute +is selected for the name <guilabel>From</guilabel>, &ie; the text will +be shown in bold letters in the article window. Of course, you can +combine different attributes, for example <guilabel>Bold</guilabel> +and <guilabel>Underlined</guilabel>.</para> + +</sect3> + +<sect3> +<title>Value</title> + +<para>Here you can influence the way the header text is displayed +in the article window; for example, if the +<guilabel>Italic</guilabel> entry is selected the sender, ⪚ <quote>John Doe +<johndoe@doubleguns.com></quote> will appears in an italic +font.</para> + +</sect3> + +<sect3> +<title>Add and remove header lines to the display</title> + +<para>To explain the possibilities of this dialog to you we're going +to add a new header line to the display.</para> + +<example> +<title>Show the newsreader used for a post in the article window</title> + +<para>This pictures shows the dialog with the header line +<literal>X-Newsreader</literal>.</para> +<screenshot> +<screeninfo>The Header Properties dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-edit-header2.png" format="PNG"/></imageobject> +<textobject> +<phrase>The Header Properties dialog</phrase> +</textobject> +<caption> +<para>The Header Properties dialog</para> +</caption> +</mediaobject> +</screenshot> + +<para>It would be nice if one could see which newsreader another +subscriber uses in the article window; it is actually quite easy +to do this because there is a (optional) header line which contains +the necessary information.</para> + +<para>Drop down the <guilabel>Header</guilabel> selection field and +select the <guilabel>X-Newsreader</guilabel> entry from the +list.</para> + +<para>In the <guilabel>Displayed name</guilabel> field, enter +<userinput>Newsreader</userinput>.</para> + +<para>Now you can select any attribute for the display of the field +and its content; next, acknowledge your input with the +<guibutton>OK</guibutton>: the new header line appears now in the list +and will later be shown in the article window.</para> + +</example> + +<para>Use the <guibutton>up</guibutton> and +<guibutton>Down</guibutton> buttons to arrange the order of the +headers in the article window.</para> + +<tip> +<para>The statement that the new header line will be shown in the +article window is actually pretty optimistic, because the entry +X-Newsreader isn't required for Usenet articles; therefore, not all +articles will contain that header line: if the line doesn't exist, the +according entry simply won't be shown. You can get more information +about headers at <ulink +url="http://www.kirchwitz.de/~amk/dni/headerzeilen">http://www.kirchwitz.de/~amk +/dni/headerzeilen</ulink> +(german)</para> +</tip> +</sect3> +</sect2> + +<sect2> +<title><guilabel>Viewer</guilabel></title> + +<sect3> +<title><guilabel>Show fancy header decorations</guilabel></title> + +<para>If this is active, the headers will be 'beautified' a +bit; otherwise, only the plain text is shown.</para> + +</sect3> + +<sect3> +<title><guilabel>Rewrap text when necessary</guilabel></title> + +<para>If this option is active, the text wrapping in the viewer will +be automatically corrected.</para> + +</sect3> + +<sect3> +<title><guilabel>Remove trailing empty lines</guilabel></title> + +<para>If this is active empty lines at the end of the article will +be automatically hidden.</para> + +</sect3> + +<sect3> +<title><guilabel>Show signature</guilabel></title> + +<para>If this setting is activated, the +<glossterm>signature</glossterm> of the sender is displayed in the +article window; if it isn't, the signature is surpressed.</para> + +<caution> +<para>Please notice that &knode; can display the signature +correctly only if it can be separated correctly from the article +content in the current article: there are newsreaders which do this +separation incorrectly. Two <quote>-</quote> characters followed by a +<quote> </quote> (space) is correct.</para> +</caution> + +<tip> +<para>Many participants in the newsgroups give hints on their homepage +or say that they have intentionally erroneously specified their Email addresses +in the header fields: if you disable displaying the signature, you might +lose this information; on the other hand, you might save yourself +from reading strange quotes.</para> +</tip> +</sect3> + +<sect3> +<title><guilabel>Interpret text-format tags</guilabel></title> + +<para>If this is active, all text format tags in the message like +<literal>*bold*</literal>, <literal>/italic/</literal> and +<literal>_underline_</literal> are shown directly in the viewer. These +text-format tags are an unofficial standard.</para> + +</sect3> + +<sect3> +<title><guilabel>Recognize quote characters</guilabel></title> + +<para>To display the quoted text in another size or color, &knode; +needs to recognize that it's quoted text. Quoted text is normally +marked with a <quote>></quote> at the beginning of the line, but +sometimes there are other characters. In this field you can enter all +characters that should mark quoted text.</para> + +</sect3> + +<sect3> +<title><guilabel>Show attachments inline if +possible</guilabel></title> + +<para>If this setting is marked, &knode; tries to display the contents +of possible attachment directly in the window when opening an +article; for instance, a picture would be displayed directly below the +article text.</para> + +<para>Additionally, you have the possibility to save the attachment or +open it with the application you have associated with the +<acronym>MIME</acronym> type of the attachment by using the context +menu.</para> + +</sect3> + +<sect3> +<title><guilabel>Open attachments on click</guilabel></title> + +<para>If this box is checked, attachments are opened with the external +program which is configured for the <acronym>MIME</acronym> type; if +there is no such association, a dialog for saving a file is opened and +you can save the attachment to a separate file.</para> + +</sect3> + +<sect3> +<title><guilabel>Show alternative contents as +attachments</guilabel></title> + +<para>Articles which are sent as Multipart <acronym>MIME</acronym> +contain the text of the message in multiple formats, for example as +raw text and <acronym>HTML</acronym>; the newsreader decides which +part of the article is displayed. This setting makes it possible for +the other formats to be opened as if they were attachments with a +mouse click.</para> + +<para>If this setting is disabled, alternative contents are not +displayed.</para> + +</sect3> + +<sect3> +<title><guilabel>Open links with</guilabel></title> + +<para>Here you can select which browser is used for displaying links +you clicked on in a message. Currently, you can either select the +<application>Netscape Navigator</application> or the default, +&konqueror;; the selected browser has to be installed, of +course.</para> + +</sect3> +</sect2> + +<sect2 id="knode-post-news-settings"> +<title>Settings for publishing articles</title> + +<para>When you post articles with &knode; the settings in the +following dialog box are used.</para> + +<screenshot> +<screeninfo>The Technical Settings dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-post-settings.png" format="PNG"/></imageobject> +<textobject> +<phrase>The Technical Settings dialog</phrase> +</textobject> +<caption> +<para>The Technical Settings dialog</para> +</caption> +</mediaobject> +</screenshot> + +<caution> +<para>If you choose the wrong settings here your articles could be +unreadable or not sendable at all, so please be careful with these +settings.</para> +</caution> + +<sect3> +<title><guilabel>Charset</guilabel></title> + +<para>Here you can choose the charset used for encoding your +articles. Normally this is <acronym>US-ASCII</acronym> for English +speaking countries, but your charset may differ. The default is the +charset used in your global &kde; settings, so you should not have to +change this.</para> + +<para>When you want to post articles in newsgroups with other charsets +(⪚ eastern European or Asian) you can set the required charset +here.</para> + +</sect3> + +<sect3> +<title><guilabel>Encoding</guilabel></title> + +<para>Here you set the encoding of the characters for the message +transfer; you can choose between 8-bit and 7-bit +(quoted-printable).</para> + +<para>If you choose 8-bit encoding most special characters are +transfered correctly; this is, for example, the normal option for the +German groups (de.*).</para> + +<para>If you choose quoted-printable 8-bit characters (⪚ German +umlauts or special characters) are send as encoded 7-bit +characters.</para> + +<tip> +<para>In the English newsgroups 7-bit encoding is quite +normal.</para> +</tip> + +</sect3> + +<sect3> +<title><guilabel>Use own default charset when +replying</guilabel></title> + +<para>If this option is active, &knode; uses your default charset for +replying instead of the charset of the article you're answering +on.</para> + +</sect3> + +<sect3> +<title><guilabel>Generate Message-ID</guilabel></title> + +<para>When this is active, &knode; generates its own Message-IDs for +all articles you post.</para> + +<caution> +<para>The Message-ID must be unique worldwide: there would +otherwise be collisions between messages with the same Message-ID and the +news server would reject the second article because it thinks +this article has already been received.</para> + +<para>A Message-ID consists of a valid <acronym>FQDN</acronym> (Full +Qualified Domain Name); this means it looks similar to an email +address with an identification before the <literal>@</literal> and the +domain.</para> + +<para>The identification is generated by &knode; automatically, but +you must provide a valid domain name in <guilabel>Hostname</guilabel>; +if you do not have your own domain, you should not activate this +option — let the newsserver generate a Message-ID for you.</para> + +<example> +<title>Message-ID</title> + +<para>An example for a valid domain would be: +<literal>kde.org</literal>; a Message-ID generated with this domain +would look like:</para> + +<screen>934lek9934@kde.org</screen> +</example> + +<para>An unique identification is only guaranteed if you have your +own domain. Even when you do not use &knode; for generating your +Message-IDs there may be collisions when you are using a local +newsserver; for example, <application>leafnode</application> generates +a Message-ID which it derives from the local hostname.</para> + +</caution> + +<tip> +<para>You can get more information about this and how to own a free domain at +<ulink +url="http://www.qad.org/faq/faq-messageid.html">http://www.qad.org/faq/faq- +messageid.html</ulink>.</para> +</tip> +</sect3> + +<sect3> +<title><guilabel>Hostname</guilabel></title> + +<para>Here you enter the Hostname of your computer; this is used to +generate the Message-ID. If you do not have your own domain you +should not activate this option — let the newsserver generate a +Message-ID for you. Using the example above this would be: +<userinput>kde.org</userinput>.</para> + +</sect3> + +<sect3> +<title><guilabel>X-Headers</guilabel></title> + +<para>Here you can enter X-Headers which are not provided by &knode;; +for example, <userinput>X-No-Archive: yes</userinput>, which can be +used to prevent your articles from being archived by archive services +such as Google.</para> + +<para>X-Headers are experimental headers, which are not included in the +standard for Internet-Messages; they are, for example, used for +extended information transfer. To prevent collisions with later +standard headers, they have a <quote>X-</quote> prefix.</para> + +</sect3> + +<sect3> +<title><guilabel>Don't add the "User-Agent" identification +header</guilabel></title> + +<para>When this option is checked &knode; does not include the +corresponding line in the Header before posting.</para> + +<para>This header is used for identification of the newsreader the +article was written in; apart from statistical reasons, this allows +non-standard newsreaders to be identified. You should not activate this +option — &knode; has no need to hide.</para> +</sect3> +</sect2> + +<sect2 id="knode-composer-settings"> +<title>The Composer Settings</title> + +<screenshot> +<screeninfo>The Composer Settings dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-composer-settings.png" format="PNG"/></imageobject> +<textobject> +<phrase>The Composer Settings dialog</phrase> +</textobject> +<caption> +<para>The Composer Settings dialog</para> +</caption> +</mediaobject> +</screenshot> + +<sect3> +<title><guilabel>Word-wrap at column</guilabel></title> + +<para>Here you can set the column number at which &knode; wraps the +line; also, you can deactivate the automatic word-wrapping +completely.</para> + +<tip> +<para>It is recommended to use no more than 76 characters even if +you are able to display more: many Usenet users use text-based +newsreaders which can not display more than 80 characters and it is +difficult to read your articles in such a newsreader if you increase +this value — this would reduce the probability of your articles +being read at all.</para> +</tip> +</sect3> + +<sect3> +<title><guilabel>Append signature automatically</guilabel></title> + +<para>When you write a new <glossterm>article</glossterm> or a +<glossterm>followup</glossterm>, your <glossterm>signature</glossterm> +is appended automatically if you have configured one in +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode...</guimenuitem><guilabel>Identity</guilabel></menuchoice>.</para> + +</sect3> + +<sect3> +<title><guilabel>Introduction Phrase:</guilabel></title> + +<para>When you write a followup, &knode; inserts an introduction +phrase before the quoted original text. You can put arbitrary text +here; you can also use the variables which &knode; extracts from the original +article, ⪚ the name of the author or the date the article was +written.</para> + +<para>The following variable are available:</para> + +<variablelist> +<varlistentry> +<term><varname>%NAME</varname></term> +<listitem> +<para>The name of the original author;</para> +</listitem> +</varlistentry> +<varlistentry> +<term><varname>%DATE</varname></term> +<listitem> +<para>The date on which the original article was written;</para> +</listitem> +</varlistentry> +<varlistentry> +<term><varname>%EMAIL</varname></term> +<listitem> +<para>The original author's email address;</para> +</listitem> +</varlistentry> +<varlistentry> +<term><varname>%MSID</varname></term> +<listitem> +<para>The Message-ID of the original article;</para> +</listitem> +</varlistentry> +<varlistentry> +<term><varname>%GROUP</varname></term> +<listitem> +<para>The name of the <glossterm>newsgroup</glossterm>the article +comes from.</para> +</listitem> +</varlistentry> +</variablelist> + +<tip> +<para>Keep this short, because this introductory line appears in +every followup: a long introductory line can be as repelling as +a long signature.</para> +</tip> + +<example> +<title>An example introductory line</title> + +<screen><userinput>On <varname>%DATE</varname> <varname>%NAME</varname> wrote in +<varname>%MSID</varname></userinput></screen> + +<para>Let us assume the original article was written by Konqui on +Saturday the 17th of June at 17:42:32 - 0500. The article has the +Message-ID <8igdg5.3vvijgt.3@lizard.physos.com>. &knode; will +then insert the following introductionary line.</para> + +<screen><computeroutput>On Sat, 17 Jun 2000 17:42:32 +0200 Konqui wrote in +<8igdg5.3vvijgt.3@lizard.physos.com>:</computeroutput></screen> + +</example> +</sect3> + +<sect3> +<title><guilabel>Rewrap quoted text automatically</guilabel></title> + +<para>When this is checked, the quoted text is wrapped at the correct +border value; hence, every new line will be at the correct quoting +level.</para> + +</sect3> + +<sect3> +<title><guilabel>Include the author's signature</guilabel></title> + +<para>When this is activated not only the text of the original +message, but also the signature of the author, is quoted in a +reply.</para> + +<tip> +<para>Quoting a signature is unnecessary and is often considered +impolite.</para> +</tip> +</sect3> + +<sect3> +<title><guilabel>Put the cursor below the introduction +phrase</guilabel></title> + +<para>Normally the cursor will appear below the whole message when +answering; with this option turned on the cursor appears below the +introduction phrase.</para> + +<tip> +<para>This is especially helpful if you quote an article and wish to +write between the quoted lines from top to bottom.</para> +</tip> +</sect3> + +<sect3> +<title><guilabel>Define external editor</guilabel></title> + +<para>You can define an external editor here which is opened by +selecting <menuchoice><guimenu>Tools</guimenu><guimenuitem>Start +external editor</guimenuitem></menuchoice> in the Composer +window.</para> + +<para>When <guilabel>Start external editor automatically</guilabel> is +checked the external editor is opened directly.</para> + +<caution> +<para>Notice the <varname>%f</varname> after the name of the +editor: this is a variable for the filename of the article you want to +edit; do not delete this — you will get an error message when opening +the external editor if you do.</para> +</caution> + +<tip> +<para>If you have problems with starting your external editor, the +reason may be that the editor starting in "the background"; this is called +forking: &knode; only notices the sub-process started and has finished, and +thinks you have quit the editor. The editor +<application>gvim</application> is an example for this; you can +disable the forking of <application>gvim</application> with the +commandline switch <option>-f</option>. It is recommended that you refer to +the documentation of your editor you are experiencing this problem.</para> + +<para>If you want to use <application>gvim</application> in +<guilabel>Specify Editor</guilabel> enter the following:</para> + +<para> +<userinput> +gvim -f %f</userinput> +</para> +</tip> +</sect3> + +<sect3> +<title><guilabel>Start external editor +automatically</guilabel></title> + +<para>If this option is active the external editor will be used for +editing articles.</para> + +</sect3> +</sect2> + +<sect2> +<title><guilabel>Spelling</guilabel></title> + +<para>Here you can configure the behavior of the spell +checker.</para> + +<sect3> +<title><guilabel>Create root/affix not in +dictionary</guilabel></title> + +<para>If this is checked a known word-root with an unknown affix will +be automatically accepted as a new word.</para> + +</sect3> + +<sect3> +<title><guilabel>Consider run-together words as spelling +errors</guilabel></title> + +<para>Here you can toggle if two known words that run together to form an +unknown word should be treated as an error or +not.)</para> + +</sect3> + +<sect3> +<title><guilabel>Dictionary</guilabel></title> + +<para>Here you chose the dictionary the spell-checker should +use.</para> + +</sect3> + +<sect3> +<title><guilabel>Encoding</guilabel></title> + +<para>Here you can tell &knode; which encoding should be used for +spell checking; for English text this should normally be +<acronym>US-ASCII</acronym>.</para> + +</sect3> + +<sect3> +<title><guilabel>Client</guilabel></title> + +<para>Here you can switch between the spell-checkers; you can use +<application>International Ispell</application> or +<application>Aspell</application>.</para> + +</sect3> + +</sect2> + +<sect2> +<title><guilabel>Signing and verifying</guilabel></title> + +<para>Here you can configure &knode; for signing articles with +<application>GnuPG</application> or +<application>PGP</application>. Your +<application>GnuPG</application>/<application>PGP</application> +<acronym>ID</acronym> will be built automatically from your configured +name and email address; it is identical to the from line in the +header of the <glossterm>article</glossterm>.</para> + +<sect3> +<title><guilabel>Encryption tool</guilabel></title> + +<para>Here you can choose your encryption tool.</para> + +</sect3> + +<sect3> +<title><guilabel>Keep passphrase in memory</guilabel></title> + +<para>If this option is active you only need to type the passphrase +for your private key once; &knode; will remember your passphrase until +you close &knode; again.</para> + +</sect3> + +<sect3> +<title><guilabel>Show ciphered/signed text after +composing</guilabel></title> + +<para>If this option is activated &knode; will show the signed message in +an extra window for confirmation before changing it in the +editor.</para> + +</sect3> + +<sect3> +<title>Always show the encryption keys for approval</title> + +<para>If you are using public newsgroups (on Usenet) you can safely +ignore this option as it would not be useful to encrypt messages sent +to Usenet; this option may, however, be useful in private +newsgroups on private networks where encryption is desired.</para> +<!-- FIXME: LW - I can see use for --> +<!-- encryption, on private networks etc. This needs a rewrite --> +<!-- AndrewColes: is this revision any better? --> +</sect3> + +<sect3> +<title><guilabel>Check signatures automatically</guilabel></title> + +<para>If this is marked, the <application>PGP</application> signature +of the article is automatically checked when showing the article; if +there's no mark, you can check the signature for correctness manually +with the <menuchoice><guimenu>View</guimenu><guimenuitem>Verify +PGP-Signature</guimenuitem></menuchoice> menu entry.</para> + +</sect3> + +</sect2> + + +<sect2 id="knode-article-cleanup"> +<title>The article-cleanup settings.</title> + +<para>The dialog below shows the settings for the article +cleanup; these settings are used to keep the number of articles on +your local harddisk to a reasonable number. &knode; administrates the +articles in memory so there can be some decrease in speed if you +have to many articles lying around; most of the time it makes no sense +to keep articles for a very long time. Services like Google and +Altavista make archiving unnecessary.</para> + +<caution> +<para>&knode; isn't an offline reader, so all of the +configuration refers to the headers which are managed by &knode;; if +you are running a local news server, such as +<application>leafnode</application>, you should refer to its +documentation to handle expiring the articles on the server — +&knode; cannot do this for you.</para> +</caution> + +<screenshot> +<screeninfo>The cleanup settings</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-cleanup.png" format="PNG"/></imageobject> +<textobject> +<phrase>The cleanup settings</phrase> +</textobject> +<caption> +<para>The cleanup settings</para> +</caption> +</mediaobject> +</screenshot> + +<sect3> +<title><guilabel>Expire old articles automatically</guilabel></title> + +<para>When this option is active all subscribed groups are checked for +old articles in the time interval set here; the old articles will +then be deleted.</para> + + +<tip> +<para>You can force this check by selecting +<menuchoice><guimenu>Group</guimenu><guimenuitem>Expire +group</guimenuitem></menuchoice></para> +</tip> +</sect3> + +<sect3> +<title><guilabel>Purge groups every</guilabel></title> + +<para>Here you can configure how often subscribed groups should be +checked for old <glossterm>article</glossterm>s and how often those +articles should be deleted; this option only has an effect when +<guilabel>Expire old articles automatically</guilabel> is +selected.</para> + +</sect3> + +<sect3> +<title><guilabel>Keep read articles</guilabel></title> + +<para>Read articles are deleted by the next cleanup if they are older +than this value; &knode; uses the creation date for this.</para> + +</sect3> + +<sect3> +<title><guilabel>Keep unread articles</guilabel></title> + +<para>Unread articles are deleted by the next cleanup if they are +older than this value; &knode; uses the creation date for this.</para> + +</sect3> + +<sect3> +<title><guilabel>Remove articles that are not available on the +server</guilabel></title> + +<para>It may happen that you'll see a <glossterm>header</glossterm> in +&knode; but the article is not available on the server; if this option +is set, those articles will automatically deleted in &knode;.</para> + +</sect3> + +<sect3> +<title><guilabel>Preserve threads</guilabel></title> + +<para>This selection forces a thread to be deleted only if all +articles contained in it fulfil the delete conditions; this means that a thread +will not be deleted until the last article in the thread should be +deleted.</para> + +<para>This prevents old articles in a long thread from vanishing before +the discussion has ended.</para> + +<caution> +<para>&knode; can not predict whether there will be a reply after the set +conditions are fulfilled; you will have to find your own settings for +this. Some newsgroups have days between replies; others only hours. Use +your own judgement.</para> +</caution> +</sect3> + +<sect3> +<title><guilabel>Compact folders automatically</guilabel></title> + +<para>This option refers to the memory behavior of &knode;. If an +<glossterm>article</glossterm> in a folder is deleted it will be +marked as deleted but still take up space on your hard disk; with +this option you can tell &knode; to actually delete the articles and +free the hard-disk space regularly.</para> + +<tip> +<para>You can force this check by selecting +<menuchoice><guimenu>Folder</guimenu><guimenuitem>Compact +folder</guimenuitem></menuchoice> or for all folders together with +<menuchoice><guimenu>Folder</guimenu><guimenuitem>Compact all +folders</guimenuitem></menuchoice>.</para> +</tip> +</sect3> + +<sect3> +<title><guilabel>Purge folders every</guilabel></title> + +<para>Here you can configure how often the folder is checked for +deleted articles; this option only has an effect if the +<guilabel>Compact folders automatically</guilabel> is set.</para> +</sect3> +</sect2> + +</sect1> diff --git a/doc/knode/using-morefeatures.docbook b/doc/knode/using-morefeatures.docbook new file mode 100644 index 000000000..39892bf60 --- /dev/null +++ b/doc/knode/using-morefeatures.docbook @@ -0,0 +1,855 @@ +<sect1 id="more-knode-features"> +<title>The Advanced &knode; Features</title> + +<sect2 id="using-filters"> +<title>Defining and Using Filters</title> + +<para>You may already have read about using filters in the chapter explaining +the configuration of &knode;; there, we were talking about the built-in +filters provided by &knode; there. You can configure the built-in +filters like all the others. The screenshot below shows the dialog box for +configuring the filters.</para> + +<tip><para>While filters and scoring are very powerful and have many +uses, one of the most common requirements is simply to add all posts +written by someone you don't wish to read to a +<quote>killfile</quote>. At the <link linkend="killfiles">end of this +section</link> is a quick guide to using filters and scores to create +such a killfile.</para></tip> + +<screenshot> +<screeninfo>The <guilabel>New Filter</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-edit-filter.png" format="PNG"/> </imageobject> +<textobject> +<phrase>The <guilabel>New Filter</guilabel> dialog</phrase> +</textobject> +<caption> +<para>The <guilabel>New Filter</guilabel> dialog</para> +</caption> +</mediaobject> +</screenshot> + +<para>First we will create a new filter. You may, at some point, want +to find your own articles amongst all the others; or, you may not +want to see the articles posted by a particular person at all: both cases can +be solved by a simple filter on the Sender. Here are some +examples:</para> + +<procedure> +<title>Do Not Show The Articles by a Particular Person</title> +<step performance="required" > +<para><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode...</guimenuitem><guilabel>Reading +News</guilabel><guilabel>Filters</guilabel></menuchoice></para> +</step> +<step performance="required"> +<para>Select <guibutton>New...</guibutton></para> +</step> +<step performance="required"> +<para>Insert <userinput>Do not show idiot</userinput> in the Text Box +<guilabel>Name</guilabel></para> +</step> +<step performance="required"> +<para>To make the filter appear on the menu, check <guilabel>Show +in menu</guilabel>.</para> +</step> +<step performance="required"> +<para>Go to the <guilabel>From</guilabel> area.</para> +</step> +<step performance="required"> +<para>Choose <guilabel>Does NOT contain</guilabel> from the drop-down +box.</para> +</step> +<step performance="required"> +<para>Insert the name of the person you want to ignore in the now- +active Text Box; for example, <userinput>Idiot</userinput>.</para> +</step> +<step performance="required"> +<para>Confirm the filter settings with +<guibutton>OK</guibutton>.</para> +</step> +</procedure> + +<para>The filter now shows all articles, except the ones containing +<quote>Idiot</quote> in the From: line.</para> + +<para>You can combine the settings of the 'Subject + From' tab +with the settings on the other tabs. For example:</para> + +<procedure> +<title>Show only discussion with unread follow-ups on own +articles.</title> +<step> +<para><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode...</guimenuitem><guilabel>Reading +News</guilabel><guilabel>Filters</guilabel></menuchoice></para> +</step> +<step> +<para>Select the predefined filter <guilabel>threads with own +articles</guilabel></para> +</step> +<step> +<para>Select <guibutton>Copy</guibutton></para> +</step> +<step> +<para>Insert <userinput>My threads with unread</userinput> in the +<guilabel>Name</guilabel> field.</para> +</step> +<step> +<para>Select the <guilabel>Status</guilabel> tab</para> +</step> +<step> +<para>Select <guilabel>has new followups</guilabel></para> +</step> +<step> +<para>Select <guilabel>true</guilabel> in the drop-down box next to +it.</para> +</step> +<step> +<para>Confirm the filter settings with +<guibutton>OK</guibutton></para> +<para>This filter shows all the threads your are participating in which +have unread messages; also, you have seen the possibility of using +existing filters as a base for new ones: this makes life easier for +complex filters.</para> +</step> +</procedure> + +<procedure> +<title>Show all articles, no older than 3 days, containing KNode in +the subject.</title> +<step> +<para><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode...</guimenuitem><guilabel>Reading +News</guilabel><guilabel>Filters</guilabel></menuchoice></para> +</step> +<step> +<para>Select <guibutton>Add</guibutton></para> +</step> +<step> +<para>Insert <userinput>Latest KNode threads</userinput> in the +<guilabel>Name</guilabel> field.</para> +</step> +<step> +<para>To make the filter appear in the menu, check <guilabel>show +in menu</guilabel>.</para> +</step> +<step> +<para>From the <guilabel>apply on</guilabel> drop-down box select +<guilabel>single articles</guilabel></para> +</step> +<step> +<para>Go to the <guilabel>Subject</guilabel> area and select +<guilabel>does contain</guilabel> in the drop-down box.</para> +</step> +<step> +<para>Insert <userinput>knode</userinput> in the text box.</para> +</step> +<step> +<para>Change to the <guilabel>Additional</guilabel> tab</para> +</step> +<step> +<para>Select the <guilabel>Age</guilabel> check box</para> +</step> +<step> +<para>Enter the following settings: <guilabel>0 < days <= +3</guilabel></para> +</step> +<step> +<para>Confirm the filter settings with +<guibutton>OK</guibutton></para> +<para>This filter, now, shows all articles, no older than 3 days, +containing <emphasis>knode</emphasis> in the subject.</para> +</step> +</procedure> + +<sect3 id="killfiles"> +<title>Creating a Killfile</title> + +<para>&knode; offers viewing filters (<guilabel>all</guilabel>, +<guilabel>unread only</guilabel>, <guilabel>my posts</guilabel>, +&etc;) and scoring filters (threads and articles start with a score of +zero and can be adjusted according to author, thread, &etc;).</para> + +<para>Using viewing filters you could hide articles according to +poster, but this is not really suitable when you want to kill several +posters universally.</para> + +<para>Using the scoring gives lots of control but filters +only at the thread level, i.e. you can watch and ignore threads; the +disadvantage of this, however, is that you may lose otherwise-useful +threads just because of one poster.</para> + +<para>The solution is to use these in combination.</para> + +<procedure> +<title>Creating a Killfile</title> +<step> +<para>Go to +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode</guimenuitem><guilabel>Reading +News</guilabel><guilabel>Filters</guilabel></menuchoice>.</para> +</step> + +<step> +<para>Create a new filter below <guilabel>unread</guilabel>, called +<userinput>killfile on</userinput>. Be sure that <guilabel>Apply to single +articles</guilabel> is set and then click on the +<guilabel>Additional</guilabel> tab. Set score <quote>equal to or less than +zero</quote> (<guilabel><=</guilabel>); then click the +<guibutton>OK</guibutton> until you have exited the dialog.</para> +</step> + +<step> +<para>Open an article whose author should be killed and just type +<keycombo action="simul">&Ctrl;<keycap>L</keycap></keycombo>(or +select, from the <guimenu>Scoring</guimenu> menu, <guimenuitem>Lower Score +for Author</guimenuitem>). This opens the Rule Editor (a part of +scoring). You can optionally give the rule a name that matches the +author (<userinput>Kook</userinput>, for example.) and then, if this is +to be permanent, uncheck the <guilabel>expire automatically</guilabel> +box; you'll see that this rule will change the author's score to minus +ten (or the score you entered); finally, click <guibutton>OK</guibutton>.</para> +</step> + +<step> +<para>Go to the menu item +<menuchoice><guimenu>View</guimenu><guisubmenu>Filter</guisubmenu><guimenuitem>killfile on.</guimenuitem> +</menuchoice></para> +</step> +</procedure> + +<para>This will cause any articles with scores less than zero will +disappear; to kill additional authors you only need repeat the +<keycombo action="simul">&Ctrl;<keycap>L</keycap></keycombo> part of +these instructions.</para> + +</sect3> + +</sect2> + +<sect2 id="knode-editor-advanced"> +<title>The Composer</title> +<anchor id="anc-knode-editor-advanced"/> + +<para>The &knode; composer provides many features, especially for +posting and replying to articles.</para> + +<sect3> +<title>Publish Articles in Multiple Newsgroups</title> + +<para>By selecting the Button <guilabel>Browse</guilabel> you can +choose additional newsgroups you want to publish your article +in.</para> + +<caution> +<para>It is generally undesirable to post articles in multiple +newsgroups: please think twice about it; if you are not sure where to +post your article ask in one of the possible groups — somebody will +tell you were to post.</para> +</caution> +</sect3> + +<sect3> +<title>Redirect Followups</title> + +<para>The main use of this feature is when a thread has gone +off topic for the newsgroup in which it is posted; for example, a thread may +start in a &kde; newsgroup discussing how to redirect a followup in &knode;, +but may leads to a dicussion about graphical and text based +newsreaders.</para> + +<para>Sometimes it happens that usenet users post an article into the +wrong newsgroup; very often those articles are just ignored. If it +looks like the author did this unintentionally, you might like to tell +them politely and make the followup articles go into the right +group.</para> + +<para>Another reason for using <guilabel>Followup-To:</guilabel> is a +when dealing with articles cross-posted across in multiple newsgroups: +you should take care that the replies are only posted in one single newsgroup.</para> + +<para>You can activate this by filling the text box +<guilabel>Followups - To:</guilabel>; here you can enter the suitable +group. If there are multiple newsgroups in the +<guilabel>Groups:</guilabel> field, they are shown in the drop-down +list.</para> + +<tip> +<para>If you enter <userinput>poster</userinput> here, instead of a +newsgroup, the replies will go directly to the author, not to the +newsgroup.</para> + +<para>Some people put an email address here, but this is not a valid +entry: use <userinput>poster</userinput> and correctly set your +Reply-To address in the normal &knode; settings.</para> + +</tip> + +</sect3> + +<sect3> +<title>Working With an External Editor</title> + +<para>Using <menuchoice><guimenu>Tools</guimenu><guimenuitem>Start +External Editor</guimenuitem></menuchoice> you can start an editor of +your choice for editing the reply; this way you can use your preferred +Editor for writing articles and e-mails.</para> + +</sect3> + +<sect3> +<title>Spelling</title> + +<para>By selecting +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Spelling</guimenuitem></menuchoice>, +you can check the article in the composer for spelling errors.</para> + +</sect3> + +<sect3> +<title>Sending Attachments</title> + +<para>By selecting +<menuchoice><guimenu>Attach</guimenu><guimenuitem>Attach +File</guimenuitem></menuchoice> you can open the File Selection Dialog +Box; here you can choose the file you want to attach.</para> + +<para>Most of the time, &knode; determines the correct +<acronym>MIME</acronym> type for the attachment; if &knode; detects +it incorrectly, you can correct the <acronym>MIME</acronym> type manually.</para> + +<para>This screenshot shows the Composer with 2 attachments: a text +file and a PNG picture.</para> + +<screenshot> +<screeninfo>Sending Attachments</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-composer-attachments.png" format="PNG"/> </imageobject> +<textobject> +<phrase>Sending Attachments</phrase> +</textobject> +<caption> +<para>Sending Attachments</para> +</caption> +</mediaobject> +</screenshot> + +<caution> +<para>Only do this if you know what you're doing! An incorrect +<acronym>MIME</acronym> type could cause the attachment to be sent +incorrectly, or mean that the attachment will not be able to be +rebuilt after sending.</para> +</caution> + +<tip> +<para>The English word attachment is used all over the world; you can +use it in your language, too.</para> +</tip> + +<important> +<para>In most newsgroups, attachments are prohibited: do not send +unsolicited attachments; if you are asked to send them, look who is +asking for them — normally, the person will want you to send them by +email.</para> + +<para>The news server will probably reject articles with attachments +for most groups anyway; those that do accept attachments +normally have the word <quote>binaries</quote> in their name. Some +news servers even stop carrying non-binaries newsgroups that +continuously receive attachments.</para> +</important> +</sect3> +</sect2> + +<sect2> +<title>Searching for Articles</title> + +<para>Sooner or later, you will want to search for one specific +article; the &knode; search feature is an easy way to do this.</para> + +<para>You can reach the search function by selecting +<menuchoice><guimenu>Edit</guimenu><guimenuitem>Search +Articles...</guimenuitem></menuchoice> or the by pressing +<keycap>F4</keycap>. The screenshot below shows the Search Dialog Box.</para> + +<screenshot> +<screeninfo>The Search Dialog Box</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-search.png" format="PNG"/> </imageobject> +<textobject> +<phrase>The Search Dialog Box</phrase> +</textobject> +<caption> +<para>The Search Dialog Box</para> +</caption> +</mediaobject> +</screenshot> + +<para>The Search Dialog Box has four tabs which allow several search +criteria: the first tab contains the settings for the +<guilabel>Subject</guilabel> and <guilabel>From</guilabel> criteria; the second +tab contains the settings for the <guilabel>message-IDs</guilabel> of +an article and its references; the third tab contains the settings for +the <guilabel>Status</guilabel> of an +article; the fourth tab, <guilabel>Additional</guilabel>, contains the remaining +criteria.</para> + +<para>You have probably already noticed the similarities between the Filter +Dialog Box and the Search Dialog Box: the usage is the same and should +not be too complicated if you have already defined your own +filters.</para> + +<para>&knode; always searches in the currently-active newsgroup; a +search in all newsgroups is not possible at the moment. After the +Search has finished the articles found appear in the article view; when +you close the Search Dialog Box using <guibutton>Close</guibutton> +the search results are deleted, and the old view of the newsgroup +appears again.</para> + +<sect3> +<title><guilabel>Start Search</guilabel></title> + +<para>With this button you start the Search with the search criteria +you defined; all articles in the selected newsgroup, fulfiling these +criteria, appear in the article view.</para> + +</sect3> + +<sect3> +<title><guilabel>New Search</guilabel></title> + +<para>This button resets all search criteria.</para> + +</sect3> +</sect2> + +<sect2 id="supersede-and-cancel"> +<title>Supersede and Cancel Articles</title> + +<para>This chapter deals with superseding and canceling articles. You +will not use these two features very often, but they do exist should +you, one day, need them.</para> + +<caution> +<para>Both functions need a news server prepared to handle +them; you should also remember that there is no guarantee that no one has +already read your article before it is superseded or canceled. +</para> + +<para>So first think, then post.</para> +</caution> + +<sect3> +<title>Cancel</title> + +<para>Canceling an article means deleting it from the +newsgroup.</para> + +<para>Why should you want to cancel an article? Perhaps you +flamed somebody in a rage and now you want to get this article out of +the newsgroup because you regret what you wrote: a personal insult, +read by everybody, doesn't look good, especially when you regret +it; so, there is only one thing you can do — cancel the article.</para> + +<para>Select the article you want to cancel and choose +<guimenuitem>Cancel article</guimenuitem> from its context menu. If +you are sure it is the right article, confirm &knode;s question with +<guibutton>Yes</guibutton>. Now you will be asked if you want to send the +Cancel message now or later; for this example we decide to send it +<guibutton>Later</guibutton>. You will notice the new message in the +folder <guilabel>Outbox</guilabel>.</para> + +<para>Now we want to look at the so-called cancel message. In the +subject you will find something like:</para> + +<screen> +<computeroutput>cancel of <n177m8.1m.ln@konqui.org></computeroutput> +</screen> + +<para>This strange letters between the brackets are the Message-ID of +the article you want to cancel. This message tells the newsserver to +delete your article: if you look at complete header of this message, +by selecting <menuchoice><guimenu>View</guimenu><guimenuitem>Show all +headers</guimenuitem></menuchoice>, you will notice a line with the +name <emphasis>control</emphasis> and the content <emphasis>cancel +<xxxxx@ddddd.dd></emphasis> — this line tells the server that +this message is a control message and, in our case, tells the server to +cancel your article.</para> + +<para>You can still delete the control message from the +<guilabel>Outbox</guilabel> should you change your mind.</para> + +<caution> +<para>Keep in mind that articles can only be identified by their +Message-IDs; you need this Message-ID if you want to cancel an +article. Normally, your article gets a Message-ID when it arrives at +the newsserver — that's why you can only cancel an article once +it has been published. The articles in the +<guilabel>Sent</guilabel> folder have no Message-ID, so you cannot cancel +them from there.</para> + +<para>There is one exception: if you have configured &knode; to +generate a Message-ID you can cancel you articles in folder +<guilabel>Sent</guilabel> too.</para> + +<para>&knode; allows only to cancel your own articles: it refuses to +cancel articles from other authors.</para> +</caution> + +<warning> +<para>Since the cancel feature is so easily fooled, by newsreaders +that let you cancel any post, many news servers do not acknowledge +cancel messages from posters; even if your own <acronym>ISP</acronym> +accepts the cancel and passes it on, many other servers will ignore it +<emphasis>and will not pass it on</emphasis>.</para> + +<para>You should consider any previously-sent article, canceled or +not, to be published and publicly available.</para> +</warning> + +</sect3> + +<sect3> +<title>Supersede</title> + +<para>Supersede overwrites your article with a new version. One reason +for doing this could be:</para> + +<para>You have written a long article and have already posted it; now, you +have found an error in this article: you could cancel this article, and post a +new, corrected, article; or, you can use Supersede.</para> + +<para>Select the article in the article view. From its context menu +select <guimenuitem>Supersede article...</guimenuitem>. &knode; will +ask you if you really want to overwrite this article; if you confirm with +<guibutton>Yes</guibutton> the Composer appears.</para> + +<para>In the Composer you can now make the desired corrections and +changes. You can then publish this article in the same way as you post +every other article; when the newsserver receives this article it +reads some special lines in the header which tell the newsserver to +supersede the older article. Select +<menuchoice><guimenu>File</guimenu><guimenuitem>Send +Later</guimenuitem></menuchoice> for now, because we want to look at +the article's header in the <guilabel>Outbox</guilabel>.</para> + +<para>Activate <menuchoice><guimenu>View</guimenu><guimenuitem>Show +all headers</guimenuitem></menuchoice>, because we want to see all the +headers the newsserver receives. You will notice a line like:</para> + +<para>Supersedes: <oggcm8.4n5.ln@konqi.org></para> + +<para>This is the instruction for the newsserver for superseding the +article with the Message-ID <oggcm8.4n5.ln@konqi.org> with the +new article.</para> + +<para>Besides this, Supersede is used for periodical posted articles, ⪚ + an <acronym>FAQ</acronym>. The new article supersedes the old one and + the newsgroups do not end up with lots of different versions.</para> + +<caution> +<para>Again, using this function is only possible if the article +already has a Message-ID. Normally, articles get their Message-ID from the +newsserver: this means that you can only supersede articles which have +already been published.</para> + +<para>You can configure &knode; to generate this Message-ID, then you can +supersede your articles in the folder <guilabel>Sent</guilabel>, +too.</para> + +<para>&knode; allows you to only supersede your own articles.</para> + +</caution> + +<warning> +<para>As with cancels, supersede messages have been abused in the +past, with, for example, certain parties sending hundreds or even +thousands of them to overwrite legitimate posts with random computer +generated junk; again, as with cancels, many news servers do not +honor supersede messages, nor do they pass them on.</para> +</warning> + +</sect3> +</sect2> + +<sect2 id="score-watch-ignore"> +<title>Score, watch, ignore</title> + +<anchor id="anc-score-watch-ignore"/> +<para>Score, Watch and Ignore are different names for the same +feature.</para> + +<para>By scoring a thread, you determine its importance. &knode; +allows scores between -100000 and 100000. A normal article will get a +score of 0 if you do not change this; threads with a score below 0 +are less important than average; threads with a score above 0 are more +important than average.</para> + +<para>The score is an attribute of the thread and the articles in this +thread, so you can use the score for filtering and searching +articles; for example, you can define a filter to show only +articles with a score > 0, i.e. all articles in which you are +specifically interested.</para> + +<para>The function <guilabel>Watch</guilabel> sets the score of +all article in a thread to 100; this way they get a high score and &knode; +labels them with a special icon.</para> + +<para>The function <guilabel>Ignore</guilabel> does the +opposite: it scores all articles in a thread with -100 so &knode; +does not show these articles anymore.</para> + +<tip> +<para>The English word <quote>scoring</quote> is used in many other +countries, too.</para> +</tip> + +<para>You can score an article or a thread manually with the right +mouse button or with the <guimenu>Scoring</guimenu> menu — here you can +score with <guilabel>Watch Thread</guilabel> and <guilabel>Ignore +Thread</guilabel> directly. Apart from scoring manually you can let &knode; +score the articles with scoring rules automatically; you can configure these +rules at <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode...</guimenuitem><guimenuitem>Reading +News</guimenuitem><guimenuitem>Scoring</guimenuitem></menuchoice> or +at <menuchoice><guimenu>Scoring</guimenu><guimenuitem>Edit scoring +rules...</guimenuitem></menuchoice> — the only difference between these +dialogs is that the last one has the rule-list next to the rule +configuration. In the following guide I'm using the editor that appears +if <menuchoice><guimenu>Scoring</guimenu><guimenuitem>Edit scoring +rules...</guimenuitem></menuchoice> is chosen.</para> + +<screenshot> +<screeninfo>The Rule Editor</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-rule-editor.png" format="PNG"/> </imageobject> +<textobject> +<phrase>The Rule Editor</phrase> +</textobject> +<caption> +<para>The Rule Editor</para> +</caption> +</mediaobject> +</screenshot> + +<para>The composer consists of 4 areas: on the left side is the list +of the rules; with the buttons below the list you can add, delete or +copy an existing rule; below that you have the possibility to limit +the rules which are shown — you have the choice whether to show all +rules or only the rules for a specific <glossterm>newsgroup</glossterm>.</para> + +<para>If you chose a rule-name in the list you the rule will be displayed +on the right-hand side; now you can edit the rule. At the top you can change +the name of the rule and set the newsgroups to which this rule applies. +You can choose one or +more than one group, note that group names must be separated by a +semicolon. You can choose from the subscribed groups with +the drop-down list and the <guibutton>Add group</guibutton> button; or +you can use regular expressions and wild cards, ⪚ <quote>.*</quote> for all +groups. The <guilabel>Expire rule automatically</guilabel> option +makes it possible to delete the rule automatically after the +configured number of days; this is useful if a specific person +behaves badly and you do not want to read anything from this person for a +few days.</para> + +<para>In the <guilabel>Condition</guilabel> field you enter the +condition on which this rule is activated. Normally, you can enter only +one condition, but you can change this by pressing the +<guibutton>More</guibutton> and <guibutton>Fewer</guibutton> buttons. If you +have more than one condition, you must tell knode whether all conditions +need to be fulfilled or only one of them; this can be done by choosing +<guilabel>Match all conditions</guilabel> or +<guilabel>Match any condition</guilabel> respectively. +</para> + +<para>Each condition consists of 2 drop-down lists and a text +field. In the first list you chose the part of the message which should +be used for the condition — this part will be compared with the text +field; the second drop-down list tells &knode; how it is to be +compared, for example, whether the chosen header should be identical +to the text entered in the text field, or if it just needs to match part of it. +Regular expressions are allowed, too. +If you check <guilabel>Not</guilabel> then the conditions under which +the condition is satisfied are reversed, and the condition will be satisfied +if the opposite of its shown conditions is true.</para> + +<para>Now, let's have a look at some +examples.</para> + +<itemizedlist> +<listitem> +<para>Maybe you want to filter away all the postings by Theodor +Test; to do this choose the +<guilabel>From</guilabel> header line from the first drop-down +list, choose <guilabel>is exactly the same as</guilabel> from the second +drop-down list, and enter his name in the text field. +But, before doing this you should have a +look at the <glossterm>header</glossterm> of one of Theodor's +articles and see what is in the <quote>From</quote> line.</para> +</listitem> +<listitem> +<para>If you do not want to read articles with more than 100 lines, choose +the header entry <guilabel>Lines</guilabel> from the first drop-down +list, choose <guilabel>greater than</guilabel> from the second, and enter +<userinput>100</userinput> in the text field. You probably, then, want to +score down the message.</para> +</listitem> +<listitem> +<para>Last example: of course, you're very interested in every article +that refers to &knode;. Choose the header entry +<guilabel>Subject</guilabel>, then <guilabel>contains substring</guilabel> +and enter <userinput>knode</userinput> in the text field. But what do +you do if &knode; is not mentioned in the +<guilabel>Subject</guilabel>? I suggest using a regular +expression: change <guilabel>contains substring</guilabel> to +<guilabel>matches regular expression</guilabel> and type +<userinput>knode|newsreader|usenet</userinput> into the text +field to match either knode, newsreader or usenet — the <userinput>|</userinput> symbol +means OR. Alternatively, you can make 3 conditions — one that matches knode, +one that matches newsreader and so on — and choose +<guilabel>Match any condition</guilabel>; but, this needs a lot of +space and it is not very elegant, is it?</para> +</listitem> + +</itemizedlist> + +<para>Once your condition is ready you should set an action down in the +<guilabel>Actions</guilabel> section. The most important action is +<guilabel>adjust score</guilabel>; if this action is chosen you can +raise or lower the score, by the configured value, for articles to which +this rule applies. &knode; can also show you a little message when finding +such an article or colorize the header in the article list; for example, you could make +interesting articles scraeming pink so you would notice them very +quickly.</para> + +<para>When leaving the editor, or when the +<menuchoice><guimenu>Scoring</guimenu><guimenuitem>Recalculate +scores</guimenuitem></menuchoice> menu item is chosen, the rules are executed; furthermore, +the rules are automatically used for new +<glossterm>articles</glossterm>. Scoring makes the most sense when +used with filters: by scoring some articles down and filtering them away +they won't appear in the article list.</para> + +</sect2> + +<sect2 id="group-identity"> +<title>Group identities</title> + +<para>With &knode; you can use a different identity with every +newsgroup to which you are subscribed; i.e. you can set a name, email address, +reply-to address and signature to use with that group.</para> + +<para>It is easy to set group identities. First, with the right mouse button, +click on the name of the newsgroup in which to have a different identity in; then, +select <guimenuitem>Group Properties</guimenuitem> from the context menu +that appears. In the dialog that appears the second tab contains +fields identical to the global identity settings; enter your settings here and +click <guibutton>OK</guibutton> to confirm the changes: then, your articles in +this group will always posted with this newly-entered identity.</para> + +<caution> +<para>When you unsubscribe from a group you lose its identity +settings for this group: if you re-subscribe to the group, you will need to +re-enter its identity settings. For new newsgroups, the global identity is +used.</para> +</caution> + +</sect2> + +<sect2 id="multiple-news-accounts"> +<title>Managing Multiple News Accounts</title> + +<para>&knode; can handle an unlimited number of news server accounts in +addition to your main news server; most users don't need this feature, +but it can be very useful to if your main newsserver does not provide +all groups you want to read. Typical cases of this are when support groups for +commercial software are hosted on a special, private, server or binary +newsgroups, which are only available from some servers.</para> + +<para>Another example of why you sometimes need more than one newsserver +is that sometimes not all interesting newsgroups are on one +server; in fact, there is very often only a selection of +newsgroups. For example, many servers do not support binary +groups with pictures or programs; if you want such a newsgroup and +your newsserver provider does not want to serve it you can configure +&knode; to get it from another server.</para> + +<para>Or, perhaps you find you are just subscribed to too many +newsgroups, and would like to organize them a little better; you +could set up several accounts for the same server, perhaps one for +groups you read every day, and one for groups you read less often, so +that you do not have to search for your <quote>everyday</quote> groups +in a long list of subscribed groups.</para> + +<para>In order to add an new account, open the preferences +dialog via +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode...</guimenuitem><guilabel>Accounts</guilabel><guilabel>News</guilabel> +</menuchoice>. The <guibutton>New</guibutton> button creates a new +account; you then have to enter the same data as for your first +account, typically a name for the account, the host name, and a user name +and password if the server requires authentication. When +this is done the new server will appear both in the configuration +dialog and in the group view: you can now subscribe to +newsgroups.</para> + +<para>You can delete the currently-selected account by pressing the +<guibutton>Delete</guibutton> button.</para> + +<tip> +<para>In the <guimenu>Account properties</guimenu> dialog (available +from the context menu of the newsserver) you can setup an identity for use +only on this newsserver.</para> +</tip> +</sect2> + +<sect2 id="PGP-support"> +<title>Sign and Verify Articles with <acronym>PGP</acronym></title> +<anchor id="anc-PGP-support"/> + +<para><acronym>PGP</acronym> is the most-widespread method used to encrypt or +sign data. Using the <glossterm>PGP-signature</glossterm> you can +verify if an article is really from the original author or if it has been +changed by others. You can find PGP-programs and guides at <ulink +url="http://www.pgpi.org">http://www.pgpi.org</ulink>.</para> + +<para>With &knode; you can sign an article with +<acronym>PGP</acronym> and to verify <acronym>PGP</acronym>-signed +article. After you have configured the <acronym>PGP</acronym> support, +at <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Knode...</guimenuitem><guilabel>Signing/Verifying</guilabel></menuchoice>, +you can sign articles in the editor with the +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Sign article with +PGP</guimenuitem></menuchoice> menu item — you will be asked for your passphrase +and after that the article will be signed.</para> + +<caution> +<para>Your <application>GnuPG</application>/<acronym>PGP</acronym> +<acronym>ID</acronym> is automatically built from your name and your +email address and is identical to the sender of the message +(<quote>From</quote>-header).</para> +</caution> + +<para> To verify +a <glossterm>PGP-signature</glossterm> you have to choose the menu +item <menuchoice><guimenu>View</guimenu><guimenuitem>Verify +PGP-signature</guimenuitem></menuchoice>.</para> +</sect2> + +</sect1> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +sgml-parent-document:("index.docbook" "chapter" "sect1") +End: +--> diff --git a/doc/knode/using-subscribing.docbook b/doc/knode/using-subscribing.docbook new file mode 100644 index 000000000..618ab292a --- /dev/null +++ b/doc/knode/using-subscribing.docbook @@ -0,0 +1,1367 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE sect1 PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> + +--> +<sect1 id="subscribing"> +<title>Working with newsgroups</title> + +<para>After the configuration of &knode; we will now try to get your +first news; to achieve this, you need to do some more steps of +configuration, but you will not have to do this very often.</para> + +<sect2 id="fetch-group-list"> +<title>Fetching the group-list from the news server</title> + +<anchor id="anc-fetch-group-list"/> + +<para>If you want to read a newsgroup you first have to subscribe to +it. &RMB;-click with your mouse on the entry of your newsserver in the +folder-list; from the context menu that appears select the +<guimenuitem>Subscribe to Newsgroups</guimenuitem> entry. &knode;, at +this moment, does not know which newsgroups are available from this +server and will ask you if it should fetch a list of available +newsgroups: confirm with <guibutton>Yes</guibutton>. Now you should +see the following dialog.</para> + +<screenshot> +<screeninfo>The <guilabel>Subscribe to +Newsgroups</guilabel> Dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-subscribe.png" format="PNG"/> </imageobject> +<textobject> +<phrase>The <guilabel>Subscribe to +Newsgroups</guilabel> dialog</phrase> +</textobject> +<caption> +<para>The <guilabel>Subscribe to +Newsgroups</guilabel> dialog</para> +</caption> +</mediaobject> +</screenshot> + +<para>After some time &knode; will has fetched the list of available +newsgroups and will show them in the left window, <guilabel>Groups +on</guilabel>, in a tree; this tree view shows the +newsgroup hierarchy.</para> + +<tip> +<para>You can find a short description about the structure of the usenet +and the hierarchy of the single newsgroups at <ulink +url="http://www.kirchwitz.de/~amk/dni/usenet-einfuehrung">http://www.kirchwitz.de/~amk/dni/usenet-einfuehrung</ulink> +(German).</para> +</tip> + +<sect3> +<title><guilabel>Search</guilabel></title> + +<para>The simplest method to navigate in the tree is to use +the <guilabel>Search</guilabel> input field: &knode; will filter the groups +displayed according to your input. If you are searching for +a group about &kde;, but you do not know its exact position in the +hierarchy, just type <userinput>kde</userinput> in the +<guilabel>Search</guilabel> field.</para> + +<para>When you enter the <userinput>k</userinput>, you will already +see the list changing; the second letter, <userinput>d</userinput>, +give you a significantly-reduced list of shown groups; and the final +<userinput>e</userinput> reduces the list to the groups with kde in +their name. You will most likely end with just one group:</para> + +<simplelist> +<member>comp.windows.x.kde</member> +</simplelist> + +<para>If your server carries the international groups, you might find +your list is:</para> + +<simplelist> +<member>comp.windows.x.kde</member> +<member>de.comp.os.unix.apps.kde</member> +</simplelist> + +<para>This incremental search gives you the possibility to search for +newsgroups without knowing their exact paths.</para> + +<tip> +<para>On a closer look, you will see &knode; showing the groups without +a tree if there are only a few groups left; this is not a bug, it is a +feature.</para> +</tip> +</sect3> + +<sect3> +<title><guilabel>disable tree view</guilabel></title> + +<para>Normally &knode; shows all the groups in a tree; if this option +is activated, all newsgroups are listed amongst one another.</para> + +</sect3> + +<sect3> +<title> +<guilabel>subscribed only</guilabel></title> + +<para>If <guilabel>subscribed only</guilabel> is checked the +tree-view <guilabel>Groups on</guilabel> shows only the groups you are +already subscribed to; this is very convenient if you want to +unsubscribe from some groups: you then won't have to search the whole tree +for these groups.</para> + +</sect3> + +<sect3> +<title><guilabel>new only</guilabel></title> + +<para>If <guilabel>new only</guilabel> is checked the tree-view +<guilabel>Groups on</guilabel> shows only the groups which are new +since you last fetched the group list; for this to be functional, you +first have to fetch a new group list with <guibutton>New +List</guibutton>.</para> + +<para>The <guibutton>New Groups</guibutton> button give the +possibility to show all the new groups since a specific date.</para> + +</sect3> + +<sect3> +<title><guilabel>Groups on</guilabel></title> + +<para>This list shows all newsgroups on this server; if you check one +of the checkboxes, <guilabel>subscribed only</guilabel> or +<guilabel>new only</guilabel>, you get the corresponding +selection.</para> + +</sect3> + +<sect3> +<title><guilabel>Current changes</guilabel></title> + +<para>The <guilabel>Current changes</guilabel> window shows all +changes you have made since you opened the dialog.</para> + +<para>The <guilabel>subscribe to</guilabel> list shows the newsgroups +you have chosen to subscribe to.</para> + +<para>Below you can see the <guilabel>unsubscribe +from</guilabel> list, which shows all newsgroups from which you have chosen to +unsubscribe. You cannot unsubscribe from groups you are not +subscribed to.</para> + +</sect3> + +<sect3> +<title><guilabel>New Groups</guilabel></title> + +<para>This button opens a dialog which allows you to configure the list +of new groups; you can choose between showing all groups since the +last refresh or all groups since a given date. With the date option, +&knode; provides a more-flexible possibility to check for new +groups; you can even check for new groups since before the last refresh of +the group list.</para> + +</sect3> + +<sect3> +<title><guibutton>New List</guibutton></title> + +<para>The <guibutton>New List</guibutton> button tells &knode; to +fetch a new group list from the news server.</para> + + +<para>The newsgroup hierarchy is in a constant flux; all the time +there are groups introduced, renamed or moved; some groups just +disappear: they are no longer available and get deleted. To reflect +this, &knode; gives you the possibility to refresh the the group +list. This is, normally, only needed to see if your server now +provides a group which was not there before.</para> + +<tip> +<para>If you simply want to make sure you have seen every new group, it is +more effective to use <guibutton>New Groups</guibutton>; fetching the +complete list is much more time consuming, but you do make sure that any +deleted groups vanish from the grouplist.</para> +</tip> + +<para>Unfortunately there is no guarantee that your newsserver is +providing all available newsgroups: many newsserver refuse groups +publishing binary attachments; other groups are only available from +special servers. &knode; provides you the possibility to use more than +one news-server if you want to access alternative servers providing +these groups; you can read more about this in <xref +linkend="multiple-news-accounts"/> .</para> + +</sect3> + +<sect3> +<title>Working with the dialog</title> + +<para>We now want to subscribe to the &kde; group: mark the the box +beside the name; you can now see the group in the list labelled +<guilabel>subscribe to</guilabel>. Another possibility is to use the +arrows between the two windows.</para> + +<para>If you picked the wrong newsgroup by mistake you can undo your +selection by unchecking the checkbox next to the group's name in the +<guilabel>Groups on</guilabel> window; again, you could use the +arrow (you probably noticed the arrow changing direction.)</para> + +<para>If you want to unsubscribe from a newsgroup it is as easy as +subscribing to it: you just uncheck the box next to its name. The groups +you wish to unsubscribe from are shown in the <guilabel>unsubscribe +from</guilabel> list. Again, the arrow is another way of doing things: to +correct your actions you can use the arrow again; this works as +long as the dialog is not closed by clicking +<guibutton>OK</guibutton>.</para> + +<para>As a &kde; and &knode; user you will probably want to subscribe +to the group, so make sure you checked the box and press +<guibutton>OK</guibutton>. This group now appears in the tree view +under the server entry it was chosen from; in our example this is +<emphasis>My News Account</emphasis>. If you can not see the group, +click on the cross next to the server entry or on the server entry +itself; the list of subscribed newsgroups should appear.</para> + +<para>Click on the newsgroup; now you see on the right in the article +view an empty folder: &knode; has to fetch the articles for the new +newsgroup. If you have, in +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode</guimenuitem><guimenuitem>Reading +news</guimenuitem><guimenuitem>General</guimenuitem></menuchoice>, the +check box <guilabel>Check for new article automatically</guilabel> +checked &knode; tries to fetch the articles from the server when the +newsgroup is first selected; if this is unchecked, you have to use +<menuchoice><guimenu>Account</guimenu><guimenuitem>Get new +articles</guimenuitem></menuchoice>.</para> + +<important> +<para>When you are using <application>leafnode</application> as a +server, there will be a single article in the +group: <application>leafnode</application> generates an article in +every new subscribed group; this indicates that +<application>leafnode</application> will consider this group the next +time it fetches articles. You can ignore an error message saying the +article can not be found. If you select this article you tell +<application>leafnode</application> you are really interested in this +group.</para> + +<para>You get the real articles when your local newsserver fetches +them from the Internet and provides them to you; details about this +can be found in the documentation of your local newsserver.</para> +</important> + +<para>When everything works the articles of the subscribed newsgroup +appear in the upper right window — the article view.</para> + +</sect3> +</sect2> + +<sect2 id="fetch-and-read-news"> +<title>Fetching and reading Articles</title> + +<para>&knode; always shows three views: the folder view, the article view and +the article window; you can change height and width of these views with +the mouse. If you click in a window it gets the focus; this is +important if you want to use &knode; with the keyboard. The +<keycap>Tab</keycap> key changes the focus between the views; the +currently-active view is indicated by a small colored bar over the +column headers.</para> + +<para>This picture shows &knode; with the subscribed &kde; +newsgroup.</para> + +<screenshot> +<screeninfo>The three views of &knode;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-views.png" format="PNG"/> </imageobject> +<textobject> +<phrase>The three views of &knode;</phrase> +</textobject> +<caption> +<para>The three views of &knode;</para> +</caption> +</mediaobject> +</screenshot> + +<para>It is possible to select more than one group or article. You can +select an area by clicking on the first entry with the &LMB;, holding +the &Shift; key and clicking on the last entry with the &LMB; +again.</para> + +<para>If you want to select more than one single entry, but they are +not next to each other in the list, you have to select the first by +clicking on it with the &LMB; and then select the other entries by +holding down the &Ctrl; key and clicking on them with the &LMB;.</para> + +<para>In either case you can clear your selection by clicking on +another entry with the &LMB;.</para> + +<caution> +<para> +If you have selected more than one entry you have to activate the +context menu with the &Shift; key pressed, otherwise you'll clear the +selection.</para> +</caution> + +<sect3> +<title>The Folder View</title> + +<para>The folder views contains not only the accounts you configured +— in our example this is <emphasis>My News Account</emphasis> +— but also three other folders. When you are subscribed to some +newsgroups there will be plus next to the name of the +account: clicking on the plus or the name of the account opens the +tree to show the names of the newsgroups you have chosen to subscribe +to using that account.</para> + +<tip> +<para>Using the &RMB; you can get a context menu for the selected item +(folders or newsgroups): if you select a newsgroup and choose +Properties you can, amongst other things, specify your identity for +this particular group; you can find more about this in the +<link linkend="group-identity">Local Identities</link> chapter.</para> +</tip> + +<para>When you select a newsgroup with your mouse a list of articles +of this group appears in the upper-right window; if there are no +articles in the upper-right window there are two possibilities — +either there are no articles for this newsgroup on the newsserver +or the newsserver did not fetch them yet. Select +<menuchoice><guimenu>Account</guimenu><guimenuitem>Get new articles in +all groups</guimenuitem></menuchoice>: if there are still no articles +appearing you either have some problems with your settings or there really +are no articles for this group. Try another group: if there are no +articles for this group you will probably have to work through the +first chapters, about the configuration of &knode;, again; the +<link linkend="faq">Frequently Asked Questions</link> chapter may help you, +too.</para> + +<caution> +<para>If you are using a local newsserver the articles only appear if +the newsserver has already got them from the internet; if you are using +<application>leafnode</application> this is done by the +<command>fetchnews</command> program.</para> +</caution> + +<sect4> +<title>The Newsgroup Folders</title> + +<para>The newsgroup folders appear with the name they are given by the +hierarchy on the newsserver; in our example this is +<guilabel>comp.windows.x.kde</guilabel>. You can change the name shown +in this view: in the context menu (click with the &RMB; on the +newsgroup's name) choose <menuchoice><guimenuitem>Rename +group</guimenuitem></menuchoice>, then you can change the name in the +input field. A good name for <guilabel>comp.windows.x.kde</guilabel> +would be, for example, <guilabel>The KDE Newsgroup</guilabel>.</para> + +<para>If you don't change this, the hierarchical name will still be shown.</para> + +<para>Besides the name of newsgroups the folder view shows more +information by altering its appearance: if a newsgroup contains +new articles its name is shown bold; the columns +<guilabel>Total</guilabel> and <guilabel>Unread</guilabel> also tell you +how many articles are in the corresponding group or folder and how many +are marked as unread.</para> + +</sect4> + +<sect4> +<title>The <guilabel>Outbox</guilabel> folder</title> + +<para>The <guilabel>Outbox</guilabel> folder contains all articles +which are to be sent later, or which could not be sent because +of an error. If you want to sent an article later choose +<menuchoice><guimenu>File</guimenu><guimenuitem>Send +Later</guimenuitem></menuchoice> in the editor: the article is then +filed in the <guilabel>Outbox</guilabel> folder; it is possible to +edit, delete or send these articles later.</para> + +<tip> +<para>If an article was not sent because of an error, it is stored in +this folder; you will not lose these articles.</para> +</tip> +</sect4> + +<sect4> +<title>The <guilabel>Drafts</guilabel> folder</title> + +<para>This folder is used for storing drafts of your articles; for +example, if you want to do some further work on them but you have no +time for it right now. To store an article in this folder +choose <menuchoice><guimenu>File</guimenu><guimenuitem>Save as +Draft</guimenuitem></menuchoice> in the editor.</para> + +<para>You can edit, delete and send the articles in this +folder.</para> + +</sect4> + +<sect4> +<title>The <guilabel>Sent</guilabel> Folder</title> + +<para>This folder contains copies of the articles that you have successfully +sent, including your e-mail replies; you can delete the messages in +this folder, but it will not un-send the messages already +sent.</para> + +<caution> +<para>If your are using a local newsserver an article appearing in +the folder <guilabel>Sent</guilabel> only indicates the local +newsserver received the article; it is possible this article will never +appears in any newsgroup if the local newsserver was not able to +send it for some reason. If you notice some articles not appearing in +the according newsgroup first make sure it was sent by the local +newsserver.</para> +</caution> + +<tip> +<para>If you are using <application>leafnode</application> then articles +leafnode was unable to send are normally found in +<filename>/var/spool/failed.postings</filename>.</para> +</tip> +</sect4> +</sect3> + +<sect3> +<title>The Article View</title> + +<para>The article view gives you a list of all articles in the +selected newsgroup or folder; you can change the appearance of this +view using the <guimenu>View</guimenu> menu. The uppermost row of the +view contains the column headers.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Subject</guilabel></term> +<listitem> +<para>The <guilabel>Subject</guilabel> column shows the subjects of +an articles which, most of the time, give you a clue about the content +of this article. The subject is chosen by the article author. You can +find more about this in <link linkend="post-and-mail-news">How to post +and reply to news</link>.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>From</guilabel></term> +<listitem> +<para>The <guilabel>From</guilabel> column shows the author, or their +e-mail address if the author didn't give a name. You can configure +your settings in +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode</guimenuitem><guilabel>Identity</guilabel></menuchoice>; when +you publish an article &knode; will show these settings in the +<guilabel>From</guilabel> column.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Score</guilabel></term> +<listitem> +<para>The <guilabel>Score</guilabel> column shows the scoring of an +article as a number; the default is 0. Articles which are important to +you can be scored up; articles you want to ignore can be scored +down: the range is -100000 to +100000. You can read more about this in +the <link linkend="score-watch-ignore">Scoring, Watching and +Ignoring</link> chapter.</para> +<para>The <guilabel>Score</guilabel> column is only shown if +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode...</guimenuitem><guilabel>Reading +News</guilabel><guilabel>General</guilabel><guilabel>Show article +score</guilabel></menuchoice> is activated.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Date</guilabel></term> +<listitem> +<para>The <guilabel>Date</guilabel> column shows the date and time +when the article was written.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Lines</guilabel></term> +<listitem> +<para>The <guilabel>Lines</guilabel> column shows the number of lines +of the <glossterm>article</glossterm>; this column is only shown if +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode...</guimenuitem><guilabel>Reading +News</guilabel><guilabel>General</guilabel><guilabel>Show line +count</guilabel></menuchoice> is activated.</para> +</listitem> +</varlistentry> +</variablelist> + +<sect4> +<title>The Symbols and Highlighting Used</title> + +<para>This is a short explanation of the different symbols for +labeling articles.</para> + +<itemizedlist> +<listitem> +<para><inlinemediaobject> +<imageobject> +<imagedata fileref="greyball.png" format="PNG"/> </imageobject> +</inlinemediaobject> +Already-read articles are labeled with this symbol.</para> +</listitem> +<listitem> +<para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="greyballchk.png" format="PNG"/> </imageobject> +</inlinemediaobject> +Articles labeled with this symbol are read and the body was fetched +from the server.</para> +</listitem> +<listitem> +<para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="redball.png" format="PNG"/> </imageobject> +</inlinemediaobject> +Articles labeled with this symbol are unread and the body has not yet +been fetched.</para> +</listitem> +<listitem> +<para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="redballchk.png" format="PNG"/> </imageobject> +</inlinemediaobject> +Articles labeled with this symbol are unread but the body has already +been already fetched.</para> +</listitem> +<listitem> +<para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="newsubs.png" format="PNG"/> </imageobject> +</inlinemediaobject> +Articles labeled with this symbol are part of a thread with new and/or +unread articles in it.</para> +</listitem> +<listitem> +<para> +<inlinemediaobject> +<imageobject> +<imagedata fileref="eyes.png" format="PNG"/> </imageobject> +</inlinemediaobject> +Articles labeled with this symbol are parts of a guarded thread. This +corresponds to a score of 100.</para> +</listitem> +</itemizedlist> + +<para>Besides different symbols, &knode; is using the following +highlighting:</para> + +<variablelist> +<varlistentry> +<term>Bold article subjects.</term> +<listitem> +<para>The article is new in this group; it was fetched during the last +connection with the server.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Article subjects printed in gray.</term> +<listitem> +<para>There are no unread follow-up articles.</para> +</listitem> +</varlistentry> +</variablelist> +</sect4> + +<sect4> +<title>Navigation in the Article View.</title> + +<para>You can navigate in articles, display an article and open or +close threads with your mouse or keyboard.</para> + +<para>When you select an article with your mouse its entry in the the +article view gets colored; at the same time the header and body of +this article appear in in the article window. If you want to read +another article you can use the mouse to select it, or you can use +the cursor keys. If you use the cursor keys you can move the +dashed frame to the article you want to read and then press +<keycap>Enter</keycap> to mark and display the article.</para> + +<para>There are many key commands to provide comfortable navigation +within a news group and to switching between newsgroups. Here the most +common key commands of the standard key configuration are listed; you +can configure the key bindings in +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Shortcuts</guimenuitem></menuchoice>.</para> + +<variablelist> +<varlistentry> +<term>Toggle Subthreads <keycap>T</keycap> +</term> +<listitem> +<para>The replies to an article are either shown or hidden by +multiply pressing this key; another way to open threads is +to use the <keycap>Right Arrow</keycap> key.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Filter <keycap>F6</keycap></term> +<listitem> +<para>A dialog is shown where you can choose the filter for the +articles.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Sort <keycap>F7</keycap> +</term> +<listitem> +<para>A dialog is shown where you can change the sorting of the +articles; if you choose a column for a second time it will change the +sorting direction.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Browsing articles <keycap>Space</keycap></term> +<listitem> +<para>This key gives you a convenient possibility for browsing through +the article view: by pressing this key the article in the article +window is scrolled; when you reach the end of the article by +repeatedly pressing <keycap>Space</keycap>, it takes you to the next +article; when you have read all articles in one newsgroup, +<keycap>Space</keycap> takes you to the first article of the next +newsgroup. By repeatedly pressing <keycap>Space</keycap> you can +browse through all subscribed newsgroups like this.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Next unread article <keycombo +action="simul">&Alt;<keycap>Space</keycap></keycombo> +</term> +<listitem> +<para>This key binding jumps to the next unread article. The sequence +follows the order of articles in the article view; threads are opened +if necessary.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Next unread thread <keycombo +action="simul">&Ctrl;<keycap>Space</keycap></keycombo> +</term> +<listitem> +<para>This command jumps to the next thread containing unread +articles: the first unread article is then selected and shown. The sequence +follows the order of articles in the article view.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Next article <keycap>N</keycap> +</term> +<listitem> +<para>This command jumps to the next article; the sequence follows the +order of articles in the article view. Replies in closed threads are +ignored.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Previous article <keycap>B</keycap></term> +<listitem> +<para>This command jumps to the previous article in the group; the +sequence follows the order of articles in the article view. Replies in +closed threads are ignored.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Next group <keycap> ++</keycap> +</term> +<listitem> +<para>This command jumps to the next newsgroup; the sequence follows +the order of newsgroups in the folder view.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Previous group <keycap>-</keycap> +</term> +<listitem> +<para>This command jumps to the previous newsgroup; the sequence +follows the order of newsgroups in the folder view.</para> +</listitem> +</varlistentry> +</variablelist> +</sect4> + +<sect4> +<title>Sorting and Filtering of Articles</title> + +<para>Some newsgroups are very crowded and contain lots of +articles; perhaps only some of them are interesting to you. One +possibility to keep track of the news you are interested in is +to sort your articles with a certain criterion.</para> + +<para>Sorting your articles, and choosing sorting criteria, is +done with the column titles in the article view: clicking on a column +title makes it the current sorting criterion; another click on the same +column title changes the order of sorting.</para> + +<tip> +<para>The current sorting criterion is indicated with an arrow next to +the title; this gives you an easy sign which column is used for +sorting, too. You have to make the column wide enough, though, so you +can actually see the arrow; you can change the column width by moving +the mouse pointer on the small area between two column titles: the +pointer changes its appearance to two horizontal arrows; clicking +and holding the &LMB; mouse button now allows you to change the width +of the column to the left of the mouse pointer.</para> +</tip> + +<para>&knode; gives you the possibility to reduce the flood of +articles: you can show only articles fitting specific +criteria; &knode; uses filters for this task. In the following paragraphs we +are just dealing with the predefined filters; for defining and using +your own filters please refer to the <link +linkend="using-filters">Defining and using Filters</link> chapter.</para> + +<para>Normally you will read most articles only once, and then never +again. &knode; labels the articles which are unread, but when there +are more articles in a news group than can be shown by the article +view you often have to search for unread articles: it would be much +easier to see only the new fetched and unread articles; &knode; gives +you this feature by the predefined filters.</para> + +<para>In the status line at the bottom border of your main window +next to the word <guilabel>Filter</guilabel> the actually-active +filter is shown: if you do not change the filter configuration this +is the filter <guilabel>all</guilabel>; this means all articles of a +newsgroup are shown. <guilabel>all</guilabel> is one of the predefined +filters; there are eight of them in all, which are described in more detail +here.</para> + +<variablelist> +<varlistentry> +<term> +<guilabel>All</guilabel> +</term> +<listitem> +<para>This filter is the default setting; it shows all articles in a +newsgroup. You can choose this filter by selecting +<menuchoice><guimenu>View</guimenu><guisubmenu>Filter</guisubmenu><guimenuitem>All</guimenuitem></menuchoice></para> +</listitem> +</varlistentry> +<varlistentry> +<term>Unread</term> +<listitem> +<para>This filter shows only unread articles; you can choose this +filter by selecting +<menuchoice><guimenu>View</guimenu><guisubmenu>Filter</guisubmenu><guimenuitem>Unread</guimenuitem></menuchoice></para> +</listitem> +</varlistentry> +<varlistentry> +<term> +New</term> +<listitem> +<para>This filter shows only articles fetched during the last +connection; you can choose this filter by selecting +<menuchoice><guimenu>View</guimenu><guisubmenu>Filter</guisubmenu><guimenuitem>New</guimenuitem></menuchoice></para> +</listitem> +</varlistentry> +<varlistentry> +<term>Watched</term> +<listitem> +<para>This shows only threads chosen as watched threads by you; you +may be watching a thread because, for example, you are participating in it, +or because you are particularly interested in the answers. +You can choose this filter by selecting +<menuchoice><guimenu>View</guimenu><guisubmenu>Filter</guisubmenu><guimenuitem>Watched</guimenuitem></menuchoice></para> + +<para>This filter only shows something if have you selected one or more +threads to watch; you can achieve this by selecting +<menuchoice><guimenu>Article</guimenu><guisubmenu>Thread</guisubmenu><guimenuitem>Watch</guimenuitem></menuchoice>: +next to the subject a symbol will appear, showing a pair of eyes.</para> + +</listitem> +</varlistentry> +<varlistentry> +<term>Threads With Unread</term> +<listitem> +<para>This filter shows only threads containing unread articles; you +can choose this filter by selecting +<menuchoice><guimenu>View</guimenu><guisubmenu>Filter</guisubmenu> +<guimenuitem>Threads With Unread</guimenuitem></menuchoice></para> + +</listitem> +</varlistentry> +<varlistentry> +<term>Threads With New</term> +<listitem> +<para>This filter shows only threads with newly-fetched articles; you +can choose this filter by selecting +<menuchoice><guimenu>View</guimenu><guisubmenu>Filter</guisubmenu><guimenuitem>Threads +With New</guimenuitem></menuchoice></para> +</listitem> +</varlistentry> +<varlistentry> +<term>Own articles</term> +<listitem> +<para>This filter only articles you have published; you can choose +this filter by selecting +<menuchoice><guimenu>View</guimenu><guisubmenu>Filter</guisubmenu><guimenuitem>Own +Articles</guimenuitem></menuchoice></para> + +</listitem> +</varlistentry> +<varlistentry> +<term>Threads With Own Articles</term> +<listitem> +<para>This filter only shows threads containing articles you +have published; you can +choose this filter by selecting <menuchoice><guimenu>View</guimenu> +<guisubmenu>Filter</guisubmenu><guimenuitem>Own +Articles</guimenuitem></menuchoice></para> +</listitem> + +</varlistentry> +</variablelist> + +<tip> +<para>For everyday use the <guilabel>unread</guilabel> filter is +propably the most useful: it shows all unread articles, including the +old ones. The other filters are very task-specific and are seldom used; +in the end it is a matter of taste which filter to select.</para> +</tip> +</sect4> +</sect3> + +<sect3> +<title>The Article Window</title> + +<para>The article window shows the currently-selected article. You can +scroll in it like in a normal text editor window; the difference is +that you cannot change the article — it is for reading only.</para> + +<para>By pressing the &RMB; in the article viewer you can access the +important functions in the context menu very quickly.</para> + +<para>The window itself is divided in three areas; they are explained +in more detail now.</para> + +<sect4> +<title>The Header</title> + +<para>This part shows the header lines or a part of the header. You +will recognize some information here from the article view; for +example, the subject and the address or name where the article +originated. When you click on the <guilabel>From:</guilabel> address, +&knode; opens an editor window where the email address of the author and +the subject of the referring article are already filled in for +you; this enables you to reply to the author directly from their +article.</para> + +<para>The appearance and content of the header shown by default +can be configured by choosing <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configuring +KNode...</guimenuitem><guilabel>Reading +News</guilabel><guilabel>Headers</guilabel></menuchoice>; you can +find a more-detailed view on this in <link +linkend="anc-knode-headers">Configuring the Shown +Headers</link>.</para> + +<para>By selecting +<menuchoice><guimenu>View</guimenu><guimenuitem>Show all +headers</guimenuitem></menuchoice> you force &knode; to show the whole +header as is produced by the newsreader and newsservers; normally +you do not need this view: it needs a lot of space in the article +window.</para> + +<para>The last lines of the header contain, if necessary, some +references to other articles, shown as numbers in the range from 1 to +n. These References are the articles to which the current article refers: +the article labeled with 1 is the oldest article to which this article +refers; the article with the highest number is the most-recent article +to which the current article refers.</para> + +<para>When you click on a reference the corresponding article is loaded +and shown in the article view; if the article is no longer available +you will be informed by &knode;. This will happen if +the article has been deleted by the article management of &knode; due to +its age, or your news server decided to delete it from the newsgroup; +for details on how to get such an article, please refer to the +<link linkend="faq">Frequently Asked Questions</link>.</para> + +<tip> +<para>The first lines in an article, with the subject and author +information and so on, are called +<glossterm>headers</glossterm>.</para> +</tip> +</sect4> + +<sect4> +<title>The Body of the Article</title> + +<para>The body of the article follows straight after the header; it +is the actual message the author published in the newsgroup. Be aware +that some articles may contain quotes from other articles which are +not recognizable as quotes; this depends on the news editor the author +used and their article-formatting habits.</para> + +<para>&knode; provides some formatting which can be used by articles; +at the moment the available options are:</para> + +<simplelist> +<member>/italic/</member> +<member>*bold*</member> +<member>_underlined_</member> +</simplelist> + +<para>Do not use the highlighting too often; the impact decreases +the more it is used.</para> + +<tip> +<para>The main part of the message (the contents) is called the +<glossterm>body</glossterm>.</para> +</tip> + +<para>Most of the time a quote is indicated by a prefixed > on +every line; however, there are other possible signs. If you can not directly +recognize a quote the author did not obey the rules of proper +quoting.</para> + +<para>Also, it is usual to start an answer with a +introductionary line, something like:</para> + +<informalexample> +<para>On 12/25/2000 Santa Claus wrote:</para> +</informalexample> + +<tip> +<para>Normally you do not have to concern yourself with these introductionary +lines: &knode; does this automatically when you reply to an +article; to find out how to customize this line see +<link linkend="knode-composer-settings">The Composer Settings</link> +documentation. +</para> +</tip> + +<para>In <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode...</guimenuitem><guilabel>Reading +News</guilabel><guilabel>Appearance</guilabel></menuchoice> you can +choose how the articles are shown. In particular, &knode; provides the +smart coloring of different reply levels; you can read more about this +in the chapter <link linkend="knode-appearance">Configuring the +appearance</link>.</para> + +<caution> +<para>&knode; only supports the coloring of quotes if the quoting +lines starts with special characters; you can configure these +characters at +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode...</guimenuitem><guilabel>Reading +News</guilabel><guilabel>Viewer</guilabel></menuchoice>.</para> +</caution> + +<para>When the body of an article contains links to internet addresses +you can invoke an internet browser to display the web page it links to +by clicking on the link; details about configuring this feature can be +found in <link linkend="setting-news-general">General news +settings</link>.</para> + +</sect4> + +<sect4> +<title>The Signature</title> + +<para>Below the main text of an article you can find the signature of the +author, provided you did not disable signatures in +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode...</guimenuitem><guilabel>Reading +News</guilabel><guilabel>General</guilabel></menuchoice>. The +signature is divided from the text by thin horizontal line.</para> +</sect4> + + +<sect4> +<title>Attachments and Multipart <acronym>MIME</acronym> +messages</title> + +<para>If an article contains attachments they are shown below the +signature in a table.</para> + +<para>The multipart <acronym>MIME</acronym> format allows the body of +an article to be sent in more than one format; for example, in plain-text +and in <acronym>HTML</acronym>. It depends on the newsreader which format +is used for reading the article.</para> + +<para>&knode; allows the different formats to be shown by selecting +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode...</guimenuitem><guilabel>Reading +News</guilabel><guilabel>Viewer</guilabel><guilabel>Show alternative +contents as attachments</guilabel></menuchoice>; when this option is +checked all alternative formats are shown as attachments and can be +opened and viewed.</para> + +<para>If this option is unchecked you will not be shown the different text +formats and &knode; decides which one should be shown.</para> + +</sect4> +</sect3> +</sect2> + +<sect2 id="post-and-mail-news"> +<title>Writing and Replying to Articles</title> + +<para>Before you start writing articles or replying to other Usenet +users be sure you understand the habits of the current +newsgroup; again, reading <link linkend="knode-journey">A Journey +Through Usenet</link> would be a good idea.</para> + +<para>For testing the settings of &knode; please resist sending an +article to a random newsgroup; it is not very friendly to bother +people with test articles: what if you are subscribed to a newsgroup +and half of its articles only contain the word +<quote>test</quote>? It is like somebody calling you just to +testing their phone.</para> + +<para>This is the reason for the special groups having +<quote>test</quote> in their name; for example, +<emphasis>alt.test</emphasis>. In these groups you can test everything +you want without bothering anybody; some groups even send you error +messages back.</para> + +<para>Here you can easily identify obvious mistakes, like a missing or +a wrong e-mail address or a wrongly-configured charset which doesn't +show all special characters.</para> + +<para>You can find a selection of test groups in <link +linkend="infos-testgroups">Test Groups</link>.</para> + +<para>Subscribe to one of the test groups now; some news servers have +their own test groups, which are probably less crowded.</para> + +<tip> +<para>Remember, you have to download the articles of the new +subscribed group; this may take some time if there are many articles +in the group. The only +important articles are yours and the answers by the check handler; if +you want to reduce the number of articles fetched during the test you +can configure this in +<menuchoice><guimenu>Settings</guimenu><guilabel>Configure +KNode...</guilabel><guilabel>Reading +News</guilabel><guilabel>General</guilabel><guilabel>Maximal number of +articles to fetch</guilabel></menuchoice>: if you reduce this +dramatically, you should not wait too long to fetch the new +articles after sending your test article; however, if it set too low +your article might not be fetched. A tolerably-fast news server should +provide your article right after you sent it; you might, however, have to +wait a while, at worst 1 or 2 days. Feel free to send another article +if cannot see your initial one; this is what the test groups are +for.</para> +</tip> + +<caution> +<para>When you are using a local news server the configuration of +<guilabel>Maximal number of articles to fetch</guilabel> in &knode; is +probably unnecessary; you should consult the documentation of your +news server instead.</para> +</caution> + +<para>If you did not encounter any errors unsubscribe from the +test groups and set <guilabel>Maximum number of articles to +fetch</guilabel> back to normal (1000).</para> + +<sect3> +<title>Publishing Articles</title> + +<para>You have seen most of &knode; now, but have only used it +passively so far, so let's publish a test +article now. Select the new subscribed test group in the folder +view; then, with <menuchoice><guimenu>Article</guimenu><guimenuitem>Post to +newsgroup...</guimenuitem></menuchoice>or the key <keycap>P</keycap>, +the Editor will be opened.</para> + +<para>You can use the &knode; Editor like a normal Texteditor; there +are some additional features for writing news articles though.</para> + +<para>In the editor window there are two input lines: one +for the subject, which is empty at the moment; and another for the +newsgroups this article is going to be posted to.</para> + +<para>Enter the text <userinput>This is a test</userinput> in the +subject field.</para> + +<tip> +<para>Normally, when you post an article, use a descriptive subject. Articles +without a descriptive subject are often ignored. Avoid subjects like +<quote>Help, it doesn't work !!!!!</quote> This subject gives no +information about the content of your article.</para> +</tip> + +<para>The <guilabel>Groups:</guilabel> field already contains the test +newsgroup you selected before; do not change this.</para> + +<para>Below the input field for the <glossterm>newsgroup</glossterm> +there is another inactive option field: this function is explained +later in the chapter <link linkend="knode-editor-advanced">The +editor</link>; for now it is irrelevant.</para> + +<para>For simplicity reasons we will only use a simple +sentence; type:</para> + +<screen> +<userinput>This is the body of my test article. @ $ %</userinput> +</screen> + +<para>Then, enter an empty line, followed by:</para> + +<screen> +<userinput>Did it work?</userinput> +</screen> + +<para>This may look funny to you, but it does what it is supposed to +do — test your configuration..</para> + +<para>Your article should now look like the screenshot below:</para> + +<screenshot> +<screeninfo>Your first article</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-new-article.png" format="PNG"/> </imageobject> +<textobject> +<phrase>Your first article</phrase> +</textobject> +<caption> +<para>Your first article</para> +</caption> +</mediaobject> +</screenshot> + +<para>If you are using &knode; with a local newsserver choose +<menuchoice><guimenu>File</guimenu><guimenuitem>Send +Now</guimenuitem></menuchoice> in the Editor; if you do not have a +connection to a newsserver at this point, you may want to send the +article later — you can achieve this by using +<menuchoice><guimenu>File</guimenu><guimenuitem>Send +Later</guimenuitem></menuchoice> — &knode; then stores this article +in the folder <guilabel>Outbox</guilabel>. You can start sending the +articles in the <guilabel>Outbox</guilabel> manually by selecting +<menuchoice><guimenu>File</guimenu><guimenuitem>Send pending +messages</guimenuitem></menuchoice>.</para> + +<para>After sending the article you will notice &knode; stores a copy +in the <guilabel>Sent</guilabel> folder.</para> + +<para>Depending on how fast your article is published in the according +newsgroup you can check the result after some time: mostly it is +sufficient to check for new messages immediately after sending the +article; be patient, though, it <emphasis>may</emphasis> take the article some +hours before reaching the newsgroup. If the article does not arrive +after a number of hours it is likely that something went wrong: try again; then, +if it is still not working, have a look at the <link +linkend="faq">Frequently Asked Questions</link>.</para> + +<important> +<para>Even when you are using a local news server, you have to check +for new articles: the local news server just sends the article, it does +not store it in the local newsgroup, so you have to synchronize with +an external news server if you want to see if your test article +has arrived.</para> +</important> + +<para>If the <glossterm>article</glossterm> appears in the newsgroup +you are successful; now you should check if there is the correct +sender and if the article is readable. Have a look on your +language-specific characters like the German umlauts; if they are not +readable you have to change the coding at +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode...</guimenuitem><guilabel>Posting +News</guilabel><guilabel>Technical</guilabel></menuchoice>to +<guilabel>Allow 8-bit</guilabel>. Change this and repeat your +test.</para> + +<para>If everything is right you have successfully published your first +article in usenet with &knode;.</para> + +</sect3> + +<sect3> +<title>Post Reply</title> + +<para>After successfully publishing an article we will now answer to +your own article. You want to answer the question you asked, don't +you?</para> + +<para>Select your article in the article view and press the &RMB;: a +context menu will appear; choose <guimenuitem>Followup to +newsgroup</guimenuitem>.</para> + +<para>&knode; opens the Editor again, but this time there is already a +subject filled in for you. The subject line reads:</para> + +<screen> +<computeroutput>Re: This is a test</computeroutput> +</screen> + +<para><emphasis>Re:</emphasis> is a shortcut for the Latin <quote>In +re</quote>, which translates to something along the lines of <quote>relating +to</quote>. You should not change the subject and, above all, the +<emphasis>Re:</emphasis>: most newsreaders sort threads by the +subject.</para> + +<tip> +<para>If you want to change the subject for some reason put the new +subject in front of the old and replace the Re: with a parenthesized +(Was: ... ); in our example this would look like </para> + +<informalexample> +<para>A new subject! (Was: This is a test)</para> +</informalexample> + +<para>With this kind of subject you show the other readers there is a +branch in the original discussion; this happens, for example, +when a new topic occurs in the original discussion or the original +subject has changed for some reason.</para> + +<para>If you answer to an article with such a subject, delete the +parenthesized part of the subject; the first part with a prefixed +<emphasis>Re:</emphasis> remains.</para> + +<informalexample> +<para>Re: A new subject!</para> +</informalexample> +</tip> + +<para>Let us have look at the Editor now. The contents of the article +to which we want to reply has already been copied to the Editor by &knode;; +to indicate the text is a quote every line is prefixed with a +<emphasis>></emphasis>.</para> + +<para>In front of the quoted text &knode; has put an introduction +line: the content of this line refers to the original author; you can +change the standard text of this line in +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode...</guimenuitem><guilabel>Posting +News</guilabel><guilabel>Composer</guilabel><guilabel>Introduction +Phrase:</guilabel></menuchoice>.</para> + +<para>The original article contains the question: <emphasis>Did it +work?</emphasis> We want to answer this question now.</para> + +<para>Place the cursor below the quoted question and write in the next +line:</para> + +<screen> +<userinput>Yes it worked, congratulations!</userinput> +</screen> + +<para>We are not finished yet: it is considered polite to begin with +a greeting like <quote>Hello</quote> in the first line; whether you call the +author by their name or not depends on your habits, watch the +newsgroup to get used to the habits there.</para> + +<para>Next we delete all non-mandatory parts of the quoted article; in +our case, we delete all parts except the question.</para> + +<para>With such a short text this is unnecessary, but this just an +example: if you have to read a message 100 lines long again just to +find an <citation>I agree</citation> at the end you will +understand.... Aside from this, it makes articles smaller so they use +less space on the server.</para> + +<para>At the end we say good bye.</para> + +<para>This screenshot shows our answer before sending it.</para> + +<screenshot> +<screeninfo>Your answer to your article</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-followup.png" format="PNG"/> </imageobject> +<textobject> +<phrase>Your answer to your article</phrase> +</textobject> +<caption> +<para>Your answer to your article</para> +</caption> +</mediaobject> +</screenshot> + +<tip> +<para>You can find a good guide for correct quoting at <ulink +url="http://www.afaik.de/usenet/faq/zitieren">http://www.afaik.de/usenet/faq/zitieren</ulink> +(German).</para> +</tip> + +<para>Now we still need to post our reply; like posting the original message +choose <menuchoice><guimenu>File</guimenu><guimenuitem>Send +now</guimenuitem></menuchoice> or the alternative +<menuchoice><guimenu>File</guimenu><guimenuitem>Send +later</guimenuitem></menuchoice>, if you're not online at the moment +and you're not using a local newsserver. If everything works +you will see your article in the newsgroup after a while; easy, isn't +it?</para> + +<tip> +<para>Using the <guimenu>Options</guimenu> menu you can configure whether +you want to send an email, a news article or both.</para> +</tip> +</sect3> + +<sect3> +<title>Mail Reply</title> + +<para>The Mail Reply follows the same lines as posting a reply in a +newsgroup; the only difference is that a mail reply is sent directly +to the author and does not appear in any newsgroup.</para> + +<para>Sometimes it is better to use an emailed reply instead of +posting a reply to newsgroup; they are used primarily for when you +want to correct an error or misconduct by the author, without hurting +their feelings by doing so publicly on the newsgroup.</para> + +<para>To answer with an e-mail select your article; again, +open the context menu with the right mouse button; and choose +<guimenuitem>Reply by Email</guimenuitem>: &knode; opens the Composer +with the quoted article.</para> + +<para>Subject and body are identical as when posting an article but +the <guilabel>Groups:</guilabel> field is replaced by a +<guilabel>To:</guilabel> field; here the author's email address +appears. In our example this should be your own email address, if +&knode; is set up correctly.</para> + +<para>For emails the same rules for quoting and politeness apply +as for posting an article in a newsgroup.</para> + +<para>After finishing your Reply, you can send it.</para> + +<para>The screenshot below shows the reply we distributed by email.</para> + +<screenshot> +<screeninfo>A Mail Reply</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-reply.png" format="PNG"/> </imageobject> +<textobject> +<phrase>A Mail Reply</phrase> +</textobject> +<caption> +<para>A Mail Reply</para> +</caption> +</mediaobject> +</screenshot> + +<important> +<para>The Mail Reply only works if you have used the correct settings in +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KNode...</guimenuitem><guilabel>Accounts</guilabel><guilabel>Mail</guilabel></menuchoice>.</para> + +<para>Depending on the configuration of your computer, you will find +the reply in your mailbox; you might have to connect to your +<acronym>ISP</acronym> and fetch your new mail first though.</para> +</important> + +<tip> +<para>On the <guimenu>Options</guimenu> menu you can configure whether +you want to send an email, a news article or both.</para> +</tip> +</sect3> +</sect2> +</sect1> + diff --git a/doc/knotes/Makefile.am b/doc/knotes/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/knotes/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/knotes/index.docbook b/doc/knotes/index.docbook new file mode 100644 index 000000000..89ff880f6 --- /dev/null +++ b/doc/knotes/index.docbook @@ -0,0 +1,383 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&knotes;"> + <!ENTITY package "kdepim"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &knotes; Handbook</title> + +<authorgroup> +<author> +<firstname>Fabian</firstname> +<surname>Dal Santo</surname> +<affiliation> +<address><email>linuxgnu@yahoo.com.au</email></address> +</affiliation> +</author> + +<author> +<firstname>Greg</firstname> +<othername>M.</othername> +<surname>Holmes</surname> +</author> + +<othercredit role="reviewer"> +<firstname>Lauri</firstname> +<surname>Watts</surname> +<contrib>Reviewer</contrib> +</othercredit> +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>2000</year> +<holder>Greg M. Holmes</holder> +</copyright> +<copyright> +<year>2001</year> +<holder>Fabian Del Santo</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2003-09-18</date> +<releaseinfo>3.0</releaseinfo> + +<abstract><para>&knotes; is a sticky notes application for the +desktop.</para></abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>Knotes</keyword> +<keyword>kdeutils</keyword> +<keyword>notes</keyword> +<keyword>popup</keyword> +<keyword>pop-up</keyword> +<keyword>knotes</keyword> + +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&knotes; is a program that lets you write the computer +equivalent of sticky notes. The notes are saved automatically when +you exit the program, and they display when you open the +program. </para> + +<para>You may print and mail your notes if you configure &knotes; to +use helper applications. </para> + +<para>Display features of notes such as color and font may be +customized for each note. You may also customize the +defaults. </para> + +</chapter> + +<chapter id="using-knotes"> +<title>Using &knotes;</title> + +<variablelist> +<varlistentry> +<term>Creating a new note:</term> +<listitem> +<para>To create a new note &RMB; click on the &knotes; panel +icon and select <guimenuitem>New Note</guimenuitem> or using the +shortcut <keycombo +action="simul">&Alt;&Shift;<keycap>N</keycap></keycombo>.</para> +<para>You can create a new note containing the contents of the +clipboard by selecting <guimenuitem>New Note From +Clipboard</guimenuitem> or using the shortcut <keycombo +action="simul">&Alt;&Shift;<keycap>C</keycap></keycombo>.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term>Writing your note:</term> +<listitem> +<para>To write your note, simply type the note in the space provided. +Normal keyboard and mouse editing functions are supported. +<mousebutton>Right</mousebutton> clicking in the editing space provides the +following menu options:</para> + +<itemizedlist> +<listitem><para><guimenuitem>Undo</guimenuitem></para></listitem> +<listitem><para><guimenuitem>Redo</guimenuitem></para></listitem> +<listitem><para><guimenuitem>Cut</guimenuitem></para></listitem> +<listitem><para><guimenuitem>Copy</guimenuitem></para></listitem> +<listitem><para><guimenuitem>Paste</guimenuitem></para></listitem> +<listitem><para><guimenuitem>Clear</guimenuitem></para></listitem> +<listitem><para><guimenuitem>Select All</guimenuitem></para></listitem> +</itemizedlist> +<para>Text may be selected by holding down the &LMB; and moving the +mouse, or by holding down the &Shift; key and using the +<keycap>arrow</keycap> keys.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Inserting the date:</term> +<listitem> +<para>To insert the current date in the Note &RMB; click on the title +bar of the note and select <guimenuitem>Insert +Date</guimenuitem>.</para> +<para>The current date and time will be inserted at the cursor +position in the text of the note.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Renaming a note:</term> +<listitem> +<para>To rename a note &RMB; click on the note title bar and select +<guimenuitem>Rename...</guimenuitem>.</para> +<para>Type the new name of the note in the dialog that appears. To +accept the new name, press the <guibutton>OK</guibutton> button. To +exit the dialog without renaming the note, press the +<guibutton>Cancel</guibutton> button. To clear what you have typed +and start over, click the <guibutton>Clear</guibutton> button.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Mailing a note:</term> +<listitem> +<para>To mail a note &RMB; click on the note title bar and select +<guimenuitem>Mail...</guimenuitem>.</para> +<para>What happens next depends on how you configured the Mail action in the +<guilabel>Preferences...</guilabel> dialog.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Printing a note:</term> +<listitem> +<para>To print a note &RMB; click on the note title bar and select +<guimenuitem>Print</guimenuitem>.</para> +<para>A standard &kde; print dialog will open.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Deleting a note:</term> +<listitem> +<para>To delete a note &RMB; click on the note title bar and select +<guimenuitem>Delete</guimenuitem>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Hiding a note:</term> +<listitem> +<para>To hide a note, click the <guiicon>X</guiicon> in the upper +right corner of the title bar of the note. The note will no longer be +displayed on the screen. The note itself will not be deleted.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Displaying notes:</term> +<listitem> +<para>When you start &knotes;, all notes will display on the screen. If you +hide a note and later want to display it, &LMB; on the &knotes; panel +icon and select the note you wish to display.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Desktop functions:</term> +<listitem> +<para>To send a note to a specific desktop, &RMB; click on the title +bar of the note and select <guisubmenu>To Desktop</guisubmenu>. +Choose the desktop desired, or alternatively, <guimenuitem>All +desktops</guimenuitem></para> +<para>To make the note remain on top of other windows &RMB; click on +the title bar of the note and select <guimenuitem>Always On +Top</guimenuitem>.</para> +<para>To return the note to more normal window behavior, simply repeat +this process.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Quitting &knotes;</term> +<listitem> +<para>To quit &knotes; &RMB; click on the panel icon and select +<guimenuitem>Quit</guimenuitem>.</para> +</listitem> +</varlistentry> +</variablelist> + +</chapter> + +<chapter id="configuration"> +<title>Configuration</title> + +<sect1 id="defaults"> +<title>Configuring &knotes; Default Settings</title> + +<para>To configure &knotes; &RMB; click on the panel icon. Select +<guimenuitem>Configure KNotes...</guimenuitem> The &knotes; +<guilabel>KNotes Defaults</guilabel> dialog will open.</para> + +<variablelist> +<title>The <guilabel>Display</guilabel> Section</title> +<varlistentry> +<term><guilabel>Text color:</guilabel></term> +<listitem><para>The color square shows the current text color. By clicking this +color square you open the standard &kde; color selection +dialog.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Background color:</guilabel></term> +<listitem><para>The color square shows the current background color. By +clicking this color square you open the standard &kde; color selection +dialog.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Default width:</guilabel></term> +<listitem><para>The width of the note in pixels. Edit this number as +desired.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Default height:</guilabel></term> +<listitem><para>The height of the note in pixels. Edit this number as +desired.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show note in taskbar</guilabel></term> +<listitem><para>By default, &knotes; notes do not show an entry in the +taskbar for each note. If you prefer they do so, enable this +option.</para> +</listitem> +</varlistentry> +</variablelist> + +<variablelist> +<title>The <guilabel>Editor</guilabel> Section</title> +<varlistentry> +<term><guilabel>Tab Size</guilabel></term> +<listitem><para>This is the size of the indent produced by the 	 +key in spaces. Edit this number as desired.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Auto Indent</guilabel></term> +<listitem><para>This is a check box. If selected, auto-indenting is +on.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Rich Text</guilabel></term> +<listitem> +<para>Not yet implemented</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Title Font: Click to Change</guilabel></term> +<listitem><para>You can change the font used for the title of your +notes.</para> + +<para>Click this button to open the standard &kde; font selection +dialog.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Text Font: Click to Change</guilabel></term> +<listitem> +<para>You can change the font used for the text of your notes.</para> + +<para>Click this button to open the standard &kde; font selection +dialog.</para></listitem> +</varlistentry> +</variablelist> + +<variablelist> +<title>The <guilabel>Actions</guilabel> Section</title> +<varlistentry> +<term><guilabel>Mail Action</guilabel></term> +<listitem><para>Type a mail command and any required command line switches in +this box.</para> +<para>By using <token>%f</token> in the command line you can pass +the filename of the note body to the mail command.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="customizing-display"> +<title>Customizing a Single Note Display</title> + +<para>You can customize each note independently of the global +settings. The settings you can customize are identical to those +described in the <link linkend="configuration">Configuration</link> +section, but they will apply only to the note you are changing. Any +other open notes, and any new notes you create, will use the default +settings.</para> + +<para>To customize a single note display &RMB; click on the note title +bar and select <guimenuitem>Preferences...</guimenuitem>.</para> +<para>The <guilabel>Local Settings</guilabel> dialog will open, +allowing you to configure the note.</para> +</sect1> + +</chapter> + +<chapter id="credits"> + +<title>Credits and License</title> + +<para>&knotes;</para> + +<para>Program copyright 1997 Bernd Wuebben <email>wuebben@kde.org</email></para> + +<para>Contributors:</para> +<itemizedlist> +<listitem><para>Wynn Wilkes<email>wynnw@calderasystems.com</email></para> +</listitem> +</itemizedlist> + +<para>Documentation copyright 2000 Greg M. Holmes +<email>holmegm@earthlink.net</email></para> + +<para>Documentation updated 2001 by Fabian Del Santo +<email>linuxgnu@yahoo.com.au</email> and 2003 by &Lauri.Watts; +&Lauri.Watts.mail;.</para> + + +<!-- 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/konsolekalendar/Makefile.am b/doc/konsolekalendar/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/konsolekalendar/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/konsolekalendar/index.docbook b/doc/konsolekalendar/index.docbook new file mode 100644 index 000000000..93871fb29 --- /dev/null +++ b/doc/konsolekalendar/index.docbook @@ -0,0 +1,871 @@ +<?xml version="1.0" ?> +<!-- TODO: + + Change license to GPL+QT exception + + Search for other TODOs + END TODO --> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + + <!ENTITY konsolekalendar "<application>KonsoleKalendar</application>"> + <!ENTITY kappname "KonsoleKalendar"> + <!ENTITY package "kdepim"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> +<!-- The language must NOT be changed here. --> + +<book lang="&language;"> + +<bookinfo> + +<title>The &konsolekalendar; Handbook</title> + +<authorgroup> +<author> +<firstname>Tuukka</firstname> +<surname>Pasanen</surname> +<affiliation><address><email>illuusio@mailcity.com</email></address></affiliation> +</author> + +<author> +<firstname>Allen</firstname> +<surname>Winter</surname> +<affiliation><address><email>awinterz@users.sourceforge.net</email></address></affiliation> +</author> + +<othercredit role="reviewer"> +<firstname>Malcolm</firstname> +<surname>Hunter</surname> +<affiliation><address><email>malcolm.hunter@gmx.co.uk</email></address></affiliation> +<contrib>Reviewer</contrib> +</othercredit> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2002</year><year>2004</year><holder>Tuukka Pasanen</holder> +</copyright> + +<copyright> +<year>2003</year><year>2005</year><holder>Allen Winter</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<!-- Don't change format of date and version of the documentation --> + +<date>2004-04-15</date> +<releaseinfo>1.1.1</releaseinfo> + +<abstract> +<para>&konsolekalendar; is a command line interface to &kde; calendars.</para> +</abstract> + + +<keywordset> +<keyword>KDE</keyword> +<keyword>&package;</keyword> +<keyword>&kappname;</keyword> +<keyword>KOrganizer</keyword> +</keywordset> + +</bookinfo> + + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&konsolekalendar; is a command line interface to &kde; calendars. +It lets you view, insert, remove, or modify calendar events by way of +the command line or from a scripting language. +Additionally, &konsolekalendar; can create a new &kde; calendar, +export a &kde; calendar to a variety of other formats, and +import another &kde; calendar.</para> + +<para>In its basic mode, &konsolekalendar; displays the list of +events in your default calendar for the current day (from 7:00 to 17:00).</para> + +<para>Main features of &konsolekalendar;: +<itemizedlist> +<listitem><para>View calendar entries from a start date/time to end date/time</para></listitem> +<listitem><para>Insert (add) calendar entries</para></listitem> +<listitem><para>Remove (delete) calendar entries</para></listitem> +<listitem><para>Modify (change) calendar entries</para></listitem> +<listitem><para>Create a new calendar</para></listitem> +<listitem><para>Export calendar entries to other file formats</para></listitem> +<listitem><para>Import an existing &kde; calendar</para></listitem> +</itemizedlist></para> + +<para>&konsolekalendar; is <emphasis>not</emphasis> another graphical +user interface to a &kde; calendar (i.e. &korganizer;). &konsolekalendar; +is intended solely for uses where a graphical user interface is +not practical or possible.</para> + +<para>&konsolekalendar; does <emphasis>not</emphasis> provide a full-featured +language for making queries of the user's calendar: nor is it the intention +of the authors to ever write such a capability. Primitive command line +options are provided for accessing calendar events within a consecutive +range of dates/time stamps. +</para> + +</chapter> + +<chapter id="features"> +<title>Features</title> +<para>In this chapter you'll learn about the main features of +&konsolekalendar; and how to control them using the command line parameters +(remember that &konsolekalendar; is not a graphical user interface; +it is a command line program only).</para> + +<para> +You'll learn about inserting, deleting, and changing +calendar events, and how to export events to other file formats. +The creation and importation of &kde; calendars will also be covered +in this chapter. +</para> + +<sect1 id="viewing"> +<title>Viewing Events</title> + +<para>In its default mode, or by using the <parameter>--view</parameter> +option, &konsolekalendar; will list all events within the range of a specified +date/time.</para> + +<para> +<informalexample><para>To view all of today's events (from 7:00 to 17:00), simply run:</para> + +<para> +<screen> +<prompt>%</prompt><userinput> <command>konsolekalendar</command> +</userinput> +</screen> +</para> +</informalexample> +</para> + +<para> +<informalexample><para>In this next example, we view all events for the week of August 18-22:</para> + +<para> +<screen> +<prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--view</option> <option>--date <replaceable>2003-08-18</replaceable> </option> <option>--end-date <replaceable>2003-08-22</replaceable></option> +</userinput> +</screen> +</para> +</informalexample> +</para> + +<para> +<informalexample><para>Show the next event(s) on the calendar from the current time forward:</para> + +<para> +<screen> +<prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--next</option> +</userinput> +</screen> +</para> +</informalexample> +</para> + +<para> +<informalexample><para>To view all events for the next 5 days run:</para> + +<para> +<screen> +<prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--show-next</option> <replaceable>5</replaceable> + +</userinput> +</screen> +</para> +</informalexample> +</para> + +</sect1> + +<sect1 id="inserting"> +<title>Inserting Events</title> + +<para>&konsolekalendar; can insert events into a &kde; calendar or calendar +resource using the <parameter>--add</parameter> command line argument. +Events successfully inserted will be immediately shown by &kde; calendar +applications (like &korganizer;).</para> + +<para> +<informalexample><para>In the following example, an event starting on 2003-06-04 (June 4, 2003) +at 1000 and ending at 1200 with summary "Doctor Visit" will be +inserted into the user's default calendar resource:</para> + + +<para> +<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--add</option> <option>--date <replaceable>2003-06-04</replaceable></option> <option>--time <replaceable>10:00</replaceable></option> \ +<option>--end-time <replaceable>12:00</replaceable></option> <option>--summary <replaceable>"Doctor Visit"</replaceable></option></userinput></screen> +</para> +</informalexample> +</para> + +<para> +<informalexample><para>In this example, a birthday event is added into the +user's default calendar resource:</para> + +<para> +<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--add</option> <option>--date <replaceable>2003-06-06</replaceable></option> <option>--summary <replaceable>"My Birthday"</replaceable></option> \ +<option>--description <replaceable>"Party Time"</replaceable></option></userinput></screen> +</para> +</informalexample> +</para> + +<para> +<informalexample><para> Here a one week vacation is inserted into a shared <replaceable>vacation</replaceable> calendar:</para> + +<para> +<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--add</option> <option>--file <replaceable>vacation.ics</replaceable></option> <option>--date <replaceable>2003-08-01</replaceable></option> \ +<option>--end-date <replaceable>2003-08-07</replaceable></option> <option>--summary <replaceable>"Vacation"</replaceable></option> <option>--description <replaceable>"Nobody will ever find me!"</replaceable></option></userinput></screen> +</para> +</informalexample> +</para> + +</sect1> + +<sect1 id="deleting"> +<title>Removing Entries</title> + +<para>&konsolekalendar; supports the removal of entries in a calendar file or +resource using the <parameter>--delete</parameter> command line argument. +Calendar entries to be removed are specified exactly by their Unique-string +identifier (<acronym>UID</acronym>) using the <parameter>--uid</parameter> +option. <acronym>UIDs</acronym> are found by first viewing the event, +using the <parameter>--view</parameter> option.</para> + +<para>Events successfully deleted will be immediately removed from within &kde; calendar +applications (&korganizer; for example).</para> + +<warning><para> When you delete something from the calendar you +<emphasis>cannot</emphasis> undo it! In other words, when you delete an entry +you cannot reverse the deletion. It's gone for good.</para></warning> + +<para> +<informalexample><para>Here we delete a calendar entry with <acronym>UID</acronym> <replaceable>&konsolekalendar;-1887551750.196</replaceable>:</para> + +<para> +<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--delete</option> <option>--uid <replaceable>&konsolekalendar;-1887551750.196</replaceable></option></userinput></screen> +</para> +</informalexample> +</para> + +</sect1> + +<sect1 id="changing"> +<title>Modifying Entries</title> + +<para>&konsolekalendar; supports the modification of existing entries in a calendar +file or resource using the <parameter>--change</parameter> command line argument. +Calendar entries to be modified are specified exactly by their Unique-string +identifier (<acronym>UID</acronym>) using the <parameter>--uid</parameter> +option. <acronym>UIDs</acronym> are found by first viewing the event, +using the <parameter>--view</parameter> option.</para> + +<para> +Changing behaves in the same way as inserting: you can change an event's start date +and time, end date and time, summary, location, and description. Events +successfully changed will be immediately shown modified within &kde; calendar +applications (&korganizer;).</para> + +<para><emphasis>Example:</emphasis> Here we change the summary and description +of a calendar entry with <acronym>UID</acronym> <replaceable>&konsolekalendar;-1887551750.196</replaceable>:</para> + +<para> +<informalexample> +<para> +<prompt>%</prompt><userinput> <command>konsolekalendar</command> +<option>--change</option> <option>--uid +<replaceable>&konsolekalendar;-1887551750.196</replaceable></option> +<option>--summary <replaceable>"Get my head examined"</replaceable></option> <option>--description <replaceable>"don't go to that doctor anymore!"</replaceable></option> +</userinput> +</para> +</informalexample> +</para> + +</sect1> + +<sect1 id="creating"> +<title>Creating a New Calendar File</title> + +<para>&konsolekalendar; can be used to create a new &kde; calendar file. +Since you cannot insert an entry into a calendar that does not exist, +you must create the file first using the <parameter>--create</parameter> +and <parameter>--file</parameter> command line arguments.</para> + +<para> +<informalexample><para>Create a calendar file named +<filename><replaceable>/data/share/calendars/vacation.ics</replaceable></filename>:</para> + +<para> +<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--create</option> <option>--file <replaceable>/data/share/calendars/vacation.ics</replaceable></option></userinput></screen> +</para> +</informalexample> +</para> + +</sect1> + +<sect1 id="exporting"> +<title>Exporting to Other Formats</title> + +<para>&konsolekalendar; can export a &kde; calendar to other well known formats. +Exporting is a special form of viewing. By default, events are viewed +in <quote>&konsolekalendar; text</quote> format. To change the viewing +format use the <parameter>--export-type</parameter> command line argument.</para> + +<para>To see a list of all supported export formats, use the +<parameter>--export-list</parameter> option, as in:</para> + +<para> +<informalexample> +<para> +<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--export-list</option></userinput></screen> +</para> +</informalexample> +</para> + +</sect1> + +<sect1 id="formats"> +<title>Export Formats</title> + +<para>Some, but not necessarily all, of the supported formats are +described in the this section.</para> + +<sect2 id="native-format"> +<title>&konsolekalendar; Text Format</title> + +<para>&konsolekalendar; Text Format is &konsolekalendar;'s native format +and is designed to be comfortable to read and to be parseable by follow-on +scripts.</para> + +<para>The &konsolekalendar; Text Format is: +<informalexample> +<screen> +Date:\t<Incidence Date>(dddd yyyy-MM-dd) +[\t<Incidence Start Time>(hh:mm) - <Incidence End Time>(hh:mm)] +Summary: +\t<Incidence Summary | "(no summary available)"> +Location: +\t<Incidence Location | "(no location available)"> +Description: +\t<Incidence Description | "(no description available)"> +UID: +\t<Incidence UID> +-------------------------------------------------- +</screen> +</informalexample> +</para> + +<para>For example: +<informalexample> +<screen> +Date: Tuesday 2003-11-01 + 08:00 - 09:00 +Summary: + Staff Meeting +Location: + Conference Room +Description: + Meet with the entire staff to discuss the project. +UID: + &konsolekalendar;-1128954167.1013 +-------------------------------------------------- +</screen> +</informalexample> +</para> + +</sect2> + +<sect2 id="short-format"> +<title>&konsolekalendar; Short Text Format</title> + +<para>Short Text Format provides a more compact, less verbose version of +&konsolekalendar;'s native format.</para> + +<para>The &konsolekalendar; Short Text Format is: +<informalexample> +<screen> +[--------------------------------------------------] +{<Incidence Date>(dddd yyyy-MM-dd)] +[<Incidence Start Time>(hh:mm) - <Incidence End Time>(hh:mm) | "\t"] +\t<Incidence Summary | \t>[, <Incidence Location>] +\t\t<Incidence Description | "\t"> +</screen> +</informalexample> +</para> + +<para>For example: +<informalexample> +<screen> +-------------------------------------------------- +Tuesday 2003-11-01 +08:00 - 09:00 Staff Meeting, Conference Room + Meet with the entire staff to discuss the project. +</screen> +</informalexample> +</para> + +</sect2> + +<sect2 id="csv-format"> +<title>Comma-Separated Values (<acronym>CSV</acronym>) Format</title> + +<para>Comma-Separated Value Format displays the event values in the same order +as &konsolekalendar; Text format. The only difference is that all the +information is on the same row with each field separated by a comma. +The resulting exported files can be imported directly into spreadsheet programs +like &kspread;, <application>OpenOffice.org Calc</application>, +and <application>&Microsoft; Excel</application>. +Also, <acronym>CSV</acronym> format is easy to parse with follow-on scripts.</para> + +<para>The Comma-Separated Value (<acronym>CSV</acronym>) format is: +<informalexample> +<screen> +YYYY-MM-DD,HH:MM,YYYY-MM-DD,HH:MM,Summary,Location,Description,UID +</screen> +</informalexample> +</para> + +<para>For example: +<informalexample> +<screen> +2003-11-01,08:00,2003-11-01,09:00,Staff Meeting,Conference Room,Meet in the big conference \ +room with the entire staff.,&konsolekalendar;-1128954167.1013 +</screen> +</informalexample> +</para> + +</sect2> + +<sect2 id="html-format"> +<title><acronym>HTML</acronym> Format</title> + +<para>The <acronym>HTML</acronym> export format will produce a valid +<acronym>HTML</acronym> file that can be published to the <acronym>WWW</acronym>. +This export format is not suitable for follow-on script parsing, but is +very nice for publishing calendars for easy public viewing.</para> + +<para><emphasis>TODO:</emphasis> Insert screenshot here</para> + +</sect2> + +<sect2 id="html-month-format"> +<title><acronym>HTMLmonth</acronym> Format</title> + +<para>This format produces an <acronym>HTML</acronym> file showing +all appointments in the months specified by the date range. +This export format is not suitable for follow-on script parsing, but is +very nice for publishing calendars for easy public viewing.</para> + +<para><emphasis>TODO:</emphasis> Insert screenshot here</para> + +</sect2> + +</sect1> + +<sect1 id="importing"> +<title>Importing Calendars</title> + +<para>&konsolekalendar; can import an <acronym>ICS</acronym> calendar file +into a &kde; calendar. All events from the calendar being imported from will +be inserted, including identical events. In the next &konsolekalendar; release +identical events will not be inserted.</para> + +<para> +<informalexample><para> To import calendar file +<filename><replaceable>another.ics</replaceable></filename> into calendar +<filename><replaceable>current.ics</replaceable></filename> run:</para> + +<para> +<screen><prompt>%</prompt><userinput> <command>konsolekalendar</command> <option>--import <replaceable>another.ics</replaceable></option> <option>--file <replaceable>current.ics</replaceable></option></userinput></screen> +</para> +</informalexample> +</para> + +</sect1> + +</chapter> + +<chapter id="features-commandline-options"> +<title>Command Line Arguments</title> + +<para>&konsolekalendar; supports the following options:</para> + +<informaltable> +<tgroup cols="2"> +<thead> +<row> + <entry>Option</entry> + <entry>Description</entry> +</row> +</thead> +<tbody> +<row> + <entry><option>--help, --help-all</option></entry> + <entry>Shows help about the program options.</entry> +</row> +<row> + <entry><option>--author</option></entry> + <entry>Shows the program author information.</entry> +</row> +<row> + <entry><option>-v, --version</option></entry> + <entry>Shows the program version information.</entry> +</row> +<row> + <entry><option>--license</option></entry> + <entry>Shows the program license information.</entry> +</row> +<row> + <entry><option>--verbose</option></entry> + <entry>Print helpful runtime messages.</entry> +</row> +<row> + <entry><option>--dry-run</option></entry> + <entry>Print what would have been done, but do not execute. Do not change any +files; do not insert, remove, modify any existing files, nor create any new files.</entry> +</row> +<row> + <entry><option>--file</option> + <replaceable> calendar-file</replaceable></entry> + <entry>Specify a calendar file to use. + <para>If not specified then your default &korganizer; resource is used.</para></entry> +</row> +<row> + <entry><emphasis>Major Operation Modes:</emphasis></entry> +</row> +<row> + <entry><option>--view</option></entry> + <entry>Print calendar events in specified export format.</entry> +</row> +<row> + <entry><option>--add</option></entry> + <entry>Insert an event into the calendar.</entry> +</row> +<row> + <entry><option>--change</option></entry> + <entry>Modify an existing calendar event.</entry> +</row> +<row> + <entry><option>--delete</option></entry> + <entry>Remove an existing calendar event.</entry> +</row> +<row> + <entry><option>--create</option></entry> + <entry>Create a new calendar file if one does not exist.</entry> +</row> +<row> + <entry><option>--import</option> + <replaceable> import-file</replaceable></entry> + <entry>Import this calendar to the main calendar.</entry> +</row> +<row> + <entry><emphasis>Operation modifiers:</emphasis></entry> +</row> +<row> + <entry><option>--all</option></entry> + <entry>View all calendar entries.</entry> +</row> +<row> + <entry><option>--next</option></entry> + <entry>View next activity in calendar.</entry> +</row> +<row> + <entry><option>--show-next</option> + <replaceable> days</replaceable></entry> + <entry>Starting at specified date show next # days' activities.</entry> +</row> +<row> + <entry><option>--uid</option> + <replaceable> UID</replaceable></entry> + <entry>View, delete, or change the event with this Unique-string IDentifier.</entry> +</row> +<row> + <entry><option>--date</option> + <replaceable> date</replaceable></entry> + <entry>Start at this day [YYYY-MM-DD]. Default date is Today</entry> +</row> +<row> + <entry><option>--time</option> + <replaceable> time</replaceable></entry> + <entry>Start at this time [HH:MM]. Default time for viewing is 07:00. + <para>To add or change a floating event, use the <option>--time float</option> + or the <option>--end-time float</option> options.</para></entry> +</row> +<row> + <entry><option>--end-date</option> + <replaceable> end-date</replaceable></entry> + <entry>End at this day [YYYY-MM-DD]. Default is set by <option>--date</option>.</entry> +</row> +<row> + <entry><option>--end-time</option> + <replaceable> end-time</replaceable></entry> + <entry>End at this time [HH:MM]. Default end-time for viewing is 17:00. + <para>To add or change a floating event, use the <option>--time float</option> + or the <option>--end-time float</option> options.</para></entry> +</row> +<row> + <entry><option>--epoch-start</option> + <replaceable> epoch-time</replaceable></entry> + <entry>Start at this time [seconds since epoch].</entry> +</row> +<row> + <entry><option>--epoch-end</option> + <replaceable> epoch-time</replaceable></entry> + <entry>End at this time [seconds since epoch].</entry> +</row> +<row> + <entry><option>--summary</option> + <replaceable> summary</replaceable></entry> + <entry>Add summary to event (works with add and change).</entry> +</row> +<row> + <entry><option>--description</option> + <replaceable> description</replaceable></entry> + <entry>Add description to event (works with add and change).</entry> +</row> +<row> + <entry><option>--location</option> + <replaceable> location</replaceable></entry> + <entry>Add location to event (works with add and change).</entry> +</row> +<row> + <entry><emphasis>Export options:</emphasis></entry> +</row> +<row> + <entry><option>--export-type</option> + <replaceable> export-type</replaceable></entry> + <entry>Export file type. + Default export file type is Text</entry> +</row> +<row> + <entry><option>--export-file</option> + <replaceable> export-file</replaceable></entry> + <entry>Export to file. By default, output is written to standard output.</entry> +</row> +<row> + <entry><option>--export-list</option></entry> + <entry>Print list of export types supported and exit.</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +</chapter> + +<chapter id="faq"> +<title>Questions and Answers</title> + +&reporting.bugs; +&updating.documentation; + +<qandaset id="faqlist"> +<qandaentry> +<question> +<para>What configuration files does &konsolekalendar; use?</para> +</question> +<answer> +<para>None.</para> +</answer> +</qandaentry> + + +<qandaentry> +<question> +<para>What are the application names of &konsolekalendar;?</para> +</question> +<answer> +<para>&konsolekalendar;'s application name is <application>konsolekalendar</application>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>What is the date specification format?</para> +</question> +<answer> +<para>&konsolekalendar; will reject dates specified on the command line +unless they are specified according to ISO 8601 standards, namely: +YYYY-MM-DD. Where YYYY represents a four-digit year (like 2003), MM +represents a two-digit month (01,02,..,12), and DD represents a two-digit day +(01,02,...,31).</para> +<para>&konsolekalendar; always exports dates according to the ISO 8601 format.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>What is the time specification format?</para> +</question> +<answer> +<para>&konsolekalendar; will reject times specified on the command line +unless they are specified according to ISO 8601 standards, namely: +HH:MM:SS. Where HH represents a two-digit hour (01,02,...,24), MM +represents a two-digit minute (01,02,..,60), and SS represents a two-digit +second (01,02,...,60).</para> +<para>&konsolekalendar; always exports times according to the ISO 8601 format.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Will &konsolekalendar; insert a new event that is identical to one that +already exists in the calendar?</para> +</question> +<answer> +<para>No. See next question.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How does &konsolekalendar; determine if an event is identical to one that +already exists in the calendar?</para> +</question> +<answer> +<para>&konsolekalendar; checks the specified start date and time, end date and time, +and summary against all events in the calendar. An event match is determined +if all three values match to an existing event. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Can a non-floating event be changed to a floating event?</para> +</question> +<answer> +<para>Yes. Use the <option>--time float</option> option with <option>--change</option>. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Why are event <acronym>UIDs</acronym> printed in most export formats?</para> +</question> +<answer> +<para>Because you need to specify <acronym>UIDs</acronym> to delete or +change events. +If you do not want to see event <acronym>UIDs</acronym> then use the +<emphasis>short</emphasis> export type (<option>--export-type short</option>). +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I have my question added to this <acronym>FAQ</acronym>?</para> +</question> +<answer> +<para>Send your questions to <email>illuusio@lycos.com</email>.</para> +</answer> +</qandaentry> + +</qandaset> +</chapter> + + +<chapter id="credits"> + +<title>Credits and License</title> + +<para>&konsolekalendar; Program copyright 2002,2003:</para> + +<itemizedlist> +<listitem><para>Tuukka Pasanen <email>illuusio@mailcity.com</email></para></listitem> +<listitem><para>Allen Winter <email>awinterz@users.sourceforge.net</email></para></listitem> +</itemizedlist> + +<para>Documentation copyright 2003:</para> +<itemizedlist> +<listitem><para>Allen Winter <email>awinterz@users.sourceforge.net</email></para></listitem> +<listitem><para>Tuukka Pasanen<email>illuusio@mailcity.com</email></para></listitem> +</itemizedlist> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; <!-- FDL: do not remove --> + +&underGPL; <!-- GPL License --> + +</chapter> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="obtaining-application"> +<title>How to obtain &konsolekalendar;</title> + +&install.intro.documentation; + +<para>&konsolekalendar; comes included with &kde;3 and is not available separately. +</para> + +</sect1> + +<sect1 id="requirements"> +<title>Requirements</title> + +<para>&konsolekalendar; 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.</para> + +<para>You can find a list of changes in the +<filename>ChangeLog</filename> file.</para> +</sect1> + +<sect1 id="compilation"> +<title>Compilation and installation</title> + +<para>This section provides a quick overview of the build process. +Please read <ulink url="http://developer.kde.org/build/compile_kde3_2.html"> +Compiling &kde; 3.2.x</ulink> for complete instructions.</para> + +<para>If you cannot obtain a suitable precompiled binary package, you +need to compile &konsolekalendar; yourself from source files. Get the source +package file <filename>kdepim-x.x.tar.bz2</filename>. +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 &konsolekalendar; 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/kde3</filename>: +</para> + +<para><userinput><command>./configure</command> --prefix=<replaceable>/opt/kde3</replaceable></userinput></para></note> + +</sect1> + +<sect1 id="configuration"> +<title>Configuration</title> + +<para>No special configuration is required to set up &konsolekalendar; to run +on the &kde; desktop.</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/kontact/Makefile.am b/doc/kontact/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/kontact/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kontact/calendar-sidebar-icon.png b/doc/kontact/calendar-sidebar-icon.png Binary files differnew file mode 100644 index 000000000..4aac5f086 --- /dev/null +++ b/doc/kontact/calendar-sidebar-icon.png diff --git a/doc/kontact/configuration-components.png b/doc/kontact/configuration-components.png Binary files differnew file mode 100644 index 000000000..c8c8edb4c --- /dev/null +++ b/doc/kontact/configuration-components.png diff --git a/doc/kontact/configuration-main.png b/doc/kontact/configuration-main.png Binary files differnew file mode 100644 index 000000000..b372c698f --- /dev/null +++ b/doc/kontact/configuration-main.png diff --git a/doc/kontact/configuration-select-components.png b/doc/kontact/configuration-select-components.png Binary files differnew file mode 100644 index 000000000..70752b65e --- /dev/null +++ b/doc/kontact/configuration-select-components.png diff --git a/doc/kontact/configuration-starting-component.png b/doc/kontact/configuration-starting-component.png Binary files differnew file mode 100644 index 000000000..ff8f9eaa2 --- /dev/null +++ b/doc/kontact/configuration-starting-component.png diff --git a/doc/kontact/configuration-summary-view-kpilot.png b/doc/kontact/configuration-summary-view-kpilot.png Binary files differnew file mode 100644 index 000000000..6600e4855 --- /dev/null +++ b/doc/kontact/configuration-summary-view-kpilot.png diff --git a/doc/kontact/configuration-summary-view.png b/doc/kontact/configuration-summary-view.png Binary files differnew file mode 100644 index 000000000..94b037fef --- /dev/null +++ b/doc/kontact/configuration-summary-view.png diff --git a/doc/kontact/index.docbook b/doc/kontact/index.docbook new file mode 100644 index 000000000..15a7c2c01 --- /dev/null +++ b/doc/kontact/index.docbook @@ -0,0 +1,1097 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd" [ + <!ENTITY PIM "<acronym>PIM</acronym>"> + <!ENTITY kappname "&kontact;"> + <!ENTITY package "kdepim"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> + <!ENTITY akregator "<application>Akregator</application>"> + <!ENTITY kitchensync "<application>KitchenSync</application>"> +]> + +<book id="kontact" lang="&language;"> + +<bookinfo> + +<title>The &kontact; Handbook</title> + +<authorgroup> +<author> +<firstname>Cornelius</firstname> +<surname>Schumacher</surname> +<affiliation><address><email>schumacher@kde.org</email></address></affiliation> +</author> + +<author> +<firstname>Antonio</firstname> +<surname>Salazar</surname> +<affiliation><address><email>savedfastcool@gmail.com</email></address></affiliation> +</author> + +<author> +<firstname>Daniel</firstname> +<surname>Molkentin</surname> +<affiliation><address><email>molkentin@kde.org</email></address></affiliation> +</author> +</authorgroup> + + +<copyright> +<year>2003-2005</year><holder>Cornelius Schumacher</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2005-02-22</date> +<releaseinfo>1.1</releaseinfo> + +<abstract><para>&kontact; is the integrated solution to your personal +information management (&PIM;) needs. It combines well-known &kde; +applications like &kmail;, &korganizer; and &kaddressbook; into a +single interface to provide easy access to mail, scheduling, +address book and other &PIM; functionality. </para></abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdepim</keyword> +<keyword>KMail</keyword> +<keyword>Organizer</keyword> +<keyword>KAddressBook</keyword> +<keyword>KNotes</keyword> +<keyword>Akregator</keyword> +<keyword>PIM</keyword> +<keyword>groupware</keyword> +<keyword>Outlook</keyword> +<keyword>Evolution</keyword> +</keywordset> + +</bookinfo> + + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&kontact; is the integrated solution for personal information +management. It combines the well-known &kde; applications for email, +scheduling, address book, notes, and newsgroups (&kmail;, &korganizer;, +&kaddressbook;, &knotes;, and &knode;) +into a single interface. Being +based on a true component framework &kontact; provides exactly the +same functionality as the stand-alone applications, and adds more +features, by making use of the integrated way &kontact; runs the +applications as components. Users still retain the choice of which +applications are run within &kontact; and which are run +stand-alone.</para> + +<para>In addition to the functionality of the individual applications &kontact; +provides, a summary view and advanced drag & drop features between components. +</para> + +</chapter> + + +<chapter id="components"> +<title>&kontact; Components</title> + +<para> +&kontact; integrates the following applications. See the individual +application manuals for details on how to use them. These apply to +running them as components inside &kontact; just as well as running +them stand-alone. +</para> + +<sect1 id="mail"> +<title>&kmail;</title> +<para> +<ulink url="help:kmail">&kmail;</ulink>, the &kde; mail client. +</para> +</sect1> + +<sect1 id="organizer"> +<title>&korganizer;</title> +<para> +<ulink url="help:korganizer">&korganizer;</ulink>, the &kde; organizer +and scheduling application. +</para> +</sect1> + +<sect1 id="addressbook"> +<title>&kaddressbook;</title> +<para> +<ulink url="help:kaddressbook">&kaddressbook;</ulink>, the &kde; contact + manager. +</para> +</sect1> + +<sect1 id="notes"> +<title>&knotes;</title> +<para> +<ulink url="help:knotes">&knotes;</ulink>, yellow sticky notes. +</para> +</sect1> + +<sect1 id="newsreader"> +<title>&knode;</title> +<para> +<ulink url="help:knode">&knode;</ulink>, the &kde; news reader. +</para> +</sect1> + +<sect1 id="pilot"> +<title>&kpilot;</title> +<para> +<ulink url="help:kpilot">&kpilot;</ulink>, the &kde; Pilot synchronization +application. +</para> +</sect1> + +<sect1 id="synchronization"> +<title>&kitchensync;</title> +<para> +<ulink url="help:kitchensync">&kitchensync;</ulink>, the &kde; synchronization +application. +</para> +</sect1> + +<sect1 id="feeds"> +<title>&akregator;</title> +<para> +<ulink url="help:akregator">&akregator;</ulink>, the &kde; RSS feed reader. +</para> +</sect1> + +</chapter> + +<chapter id="main-window"> +<title>The &kontact; Main Window</title> + +<para>The main window consists of a side pane on the left showing the icons of +the available components, the main view on the right which contains the main +window of the active component and the usual menu, tool and status bars.</para> + +<sect1 id="side-pane"> +<title>Side Pane</title> + +<para>The side pane serves multiple purposes. It allows for switching between +components, shows which component is active and serves as the target for +drag & drop operations to the different applications.</para> + +<screenshot> +<screeninfo>&kontact;'s Side Pane</screeninfo> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="side-pane.png"/></imageobject> +<textobject> +<phrase>&kontact;'s Side Pane</phrase> +</textobject> +<caption> +<para> +&kontact;'s Side Pane +</para> +</caption> +</mediaobject> +</screenshot> + +<para>For switching between components simply click on the corresponding icon. +The main window of the component is shown and the menu, tool and status bars are +adapted to reflect the functionality of the active component. If you activate a +component for the first time there might be a small delay until the main view +is changed, because components are loaded on demand. This means you don't waste +memory for components you don't use.</para> + +<para>The icons in the side pane can also be used as targets for drag & drop +operations. For example, you can drag a mail from the mail part and +drop it on the icon of the todo list or the calendar to create a todo +or event associated with this mail.</para> + +<para>Finally, you can change the size of the icons in the side pane. +Right-clicking on the side pane will give you the option to use Large, +Normal, or Small icons, as well as the option to use text only +instead of icons.</para> + +<para>If you dislike the sidebar, you can simply hide it by dragging the +splitter. An alternative navigation between part is provided by the +<guilabel>navigator</guilabel> toolbar, which will always be aligned on the opposite +side of the mainwindow from the side pane.</para> + +</sect1> + + +<sect1 id="main-view"> + +<title>Main View</title> + +<para>The view on the right which takes up most of the area of the &kontact; +main window shows the active component. This exactly corresponds to the main +window the component uses when run as a stand-alone application. The highlighted +icon in the side pane indicates to which application the main view belongs. +&kontact; remembers which component was active, so when starting &kontact; the +view initially shows which one was activated when exiting &kontact; the last +time.</para> + +<screenshot> +<screeninfo>&kontact;'s Main View</screeninfo> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="main-view.png"/></imageobject> +<textobject> +<phrase>&kontact;'s Main View</phrase> +</textobject> +<caption> +<para> + &kontact;'s Main View +</para> +</caption> +</mediaobject> +</screenshot> + +<para>In addition, there are two ways of overriding the component that &kontact; +starts in. The first is as an argument to the &kontact; program call +(see <xref linkend="command-line"/>). The second is a setting in the +&kontact; Settings dialog that will allow you to always start &kontact; in a +certain mode.</para> + +<screenshot> +<screeninfo>&kontact; Starting Component Setting</screeninfo> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="configuration-starting-component.png"/></imageobject> +<textobject> +<phrase>&kontact; Starting Component Setting</phrase> +</textobject> +<caption> +<para> + &kontact; Starting Component Setting +</para> +</caption> +</mediaobject> +</screenshot> + +</sect1> + +<sect1 id="bars"> +<title>Menu, Tool and Status Bars</title> + +<para>The menu, tool and status bars are adapted to the active component. That +means that, in addition to some common functions like the help menu which are +shown for all components, there are actions which are switched when the active +component is switched. These actions available for each component are the same +ones which are also available when running the application stand-alone.</para> + +<screenshot> +<screeninfo>Views of &kontact;'s menu bars in the Summary View, Mail View, and Calendar View</screeninfo> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="menu-bar-summary.png"/></imageobject> +<textobject> +<phrase>Views of &kontact;'s menu bars in the Summary View, Mail View, and Calendar View</phrase> +</textobject> +</mediaobject> +</screenshot> + +<screenshot> +<screeninfo>Views of &kontact;'s menu bars in the Summary View, Mail View, and Calendar View</screeninfo> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="menu-bar-kmail.png"/></imageobject> +<textobject> +<phrase>Views of &kontact;'s menu bars in the Summary View, Mail View, and Calendar View</phrase> +</textobject> +</mediaobject> +</screenshot> + +<screenshot> +<screeninfo>Views of &kontact;'s menu bars in the Summary View, Mail View, and Calendar View</screeninfo> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="menu-bar-korganizer.png"/></imageobject> +<textobject> +<phrase>Views of &kontact;'s menu bars in the Summary View, Mail View, and Calendar View</phrase> +</textobject> +<caption> +<para> + Views of &kontact;'s menu bars in the Summary View, Mail View, and Calendar View +</para> +</caption> +</mediaobject> +</screenshot> + +<para>A special action common to all components is the +<guimenuitem>New</guimenuitem> action. It allows creation of new objects +like emails, contacts, appointments and todos independently of which +component is active. The component responsible for processing the +selected object is started, if required, and takes over the created +object.</para> + +<screenshot> +<screeninfo>&kontact;'s New Menu</screeninfo> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="new-menu.png"/></imageobject> +<textobject> +<phrase>&kontact;'s New Menu</phrase> +</textobject> +<caption> +<para> +&kontact;'s New Menu +</para> +</caption> +</mediaobject> +</screenshot> +<para> +Another common action is the <guimenuitem>Synchronize</guimenuitem> action. It synchronizes mail and groupware folders depending on the active component. E.g., if the Calendar component is active, the button synchronizes all Calendar folders. In the Summary, the action synchronizes all folders independent of their content. +</para> +</sect1> + +<sect1 id="side-pane-drag-and-drop"> +<title>Drag and Drop Functionality</title> + +<para>&kontact; provides advanced drag and drop functionality between +the programs it contains. Following is a brief description of each of +the specific drag and drop operations that can be effected and the +result of each.</para> + +<sect2 id="side-pane-drag-and-drop-kmail-todo"> +<title>&kmail; -> &korganizer; Todo List</title> + +<para> +Dragging a message from +<ulink url="help:kmail/using-kmail.html#the-mail-reader-window">&kmail;'s Headers pane</ulink> +to the icon for &korganizer;'s Todo list +(<guiicon><inlinemediaobject><imageobject> +<imagedata fileref="todo-list-sidebar-icon.png" format="PNG"/> +</imageobject></inlinemediaobject></guiicon>) +will create a new Todo with +<guilabel>Mail: <replaceable>Subject</replaceable></guilabel> as the title and +<guilabel>From: <replaceable>Sender</replaceable> +To: <replaceable>Receiver</replaceable> +Subject: <replaceable>Subject</replaceable></guilabel> as the contents +(where text that looks <guilabel><replaceable>like +this</replaceable></guilabel> is information +from the message itself), as well as the e-mail message itself as an +attachment. +</para> + +</sect2> + +<sect2 id="side-pane-drag-and-drop-kmail-calendar"> +<title>&kmail; -> &korganizer; Calendar</title> + +<para> +Dragging a message from +<ulink url="help:kmail/using-kmail.html#the-mail-reader-window">&kmail;'s Headers pane</ulink> +to the icon for &korganizer;'s Calendar +(<guiicon><inlinemediaobject><imageobject> +<imagedata fileref="calendar-sidebar-icon.png" format="PNG"/> +</imageobject></inlinemediaobject></guiicon>) +will create a new Event with +<guilabel>Mail: <replaceable>Subject</replaceable></guilabel> as the title and +<guilabel>From: <replaceable>Sender</replaceable> +To: <replaceable>Receiver</replaceable> +Subject: <replaceable>Subject</replaceable></guilabel> as the contents +(where text that looks <guilabel><replaceable>like +this</replaceable></guilabel> is information +from the message itself), as well as the e-mail message itself as an +attachment. +</para> + +<para>Note that dragging onto the Todo button creates a Todo, +whereas dragging onto the Calendar creates an Event. More on this +distinction is available in the +<ulink url="help:korganizer">&korganizer; documentation</ulink> +</para> + +</sect2> + + +<sect2 id="side-pane-drag-and-drop-kmail-contacts"> +<title>&kmail; -> &kaddressbook;</title> + +<para> +Dragging a message from +<ulink url="help:kmail/using-kmail.html#the-mail-reader-window">&kmail;'s Headers pane</ulink> + to the icon for &kaddressbook; +(<guiicon><inlinemediaobject><imageobject> <imagedata + fileref="kaddressbook-sidebar-icon.png" + format="PNG" /> +</imageobject></inlinemediaobject></guiicon>) will create a contact +from the email address of the sender, unless a contact with that name +already exists. A dialog box notifies you of this action. +</para> + + +</sect2> + + +<sect2 id="side-pane-drag-and-drop-kaddressbook-todo"> +<title>&kaddressbook; -> &korganizer; Todo List</title> + +<para> +Dragging any number of entries from <ulink +url="help:kaddressbook/using-kaddressbook.html">&kaddressbook;'s main +window</ulink> to the icon for &korganizer;'s Todo List +(<guiicon><inlinemediaobject><imageobject> <imagedata + fileref="todo-list-sidebar-icon.png" + format="PNG"/> +</imageobject></inlinemediaobject></guiicon>) will create a new Todo +with "Meeting" as the title and the selected contacts as +attendees. +</para> + +<para>Note that dragging onto the Todo button creates a Todo, +whereas dragging onto the Calendar creates an Event. More on this +distinction is available in the +<ulink url="help:korganizer">&korganizer; documentation</ulink> +</para> + +</sect2> + + +<sect2 id="side-pane-drag-and-drop-kaddressbook-calendar"> +<title>&kaddressbook; -> &korganizer; Calendar</title> + +<para> +Dragging any number of entries from <ulink +url="help:kaddressbook/using-kaddressbook.html">&kaddressbook;'s main +window</ulink> to the icon for &korganizer;'s Calendar +(<guiicon><inlinemediaobject><imageobject> <imagedata + fileref="calendar-sidebar-icon.png" + format="PNG"/> +</imageobject></inlinemediaobject></guiicon>) will create a new Event +with "Meeting" as the title and the selected contacts as +attendees. +</para> + +<para>Note that dragging onto the Todo button creates a Todo, +whereas dragging onto the Calendar creates an Event. More on this +distinction is available in the +<ulink url="help:korganizer">&korganizer; documentation</ulink> +</para> + +</sect2> + +<sect2 id="side-pane-drag-and-drop-knotes-todo"> +<title>&knotes; -> &korganizer;'s Todo List</title> + +<para> +Dragging a note from &knotes; to the icon for &korganizer;'s Todo List +(<guiicon><inlinemediaobject><imageobject> <imagedata + fileref="todo-list-sidebar-icon.png" + format="PNG"/> +</imageobject></inlinemediaobject></guiicon>) will create a new Todo +with the title set to the title of the note and the description set to the note itself. +</para> + +</sect2> + + +</sect1> + +</chapter> + +<chapter id="summary-view"> +<title>The Summary View</title> + +<para>The default view when starting &kontact; for the first time is the summary +view. It shows an overview of the most relevant information provided by the +selected &kontact; components. These can be newsticker headlines, imminent +appointments or birthdays, due todos, weather data, etc. Which information is +shown is configurable by selecting the corresponding components in the <link +linkend="configuration">&kontact; configuration dialog</link>.</para> + +<screenshot> +<screeninfo>&kontact;'s Summary View</screeninfo> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="summary-view.png"/></imageobject> +<textobject> +<phrase>&kontact;'s Summary View</phrase> +</textobject> +<caption> +<para> +&kontact;'s Summary View +</para> +</caption> +</mediaobject> +</screenshot> + +<sect1 id="summary-view-component-reposition"> +<title>Repositioning Summary View Components</title> + +<para>The Summary View allows you to change where the +components are in the view itself. So, if you prefer to +have your Special Dates in the lower left and your to-dos in +the upper right, you can rearrange the summary view to +reflect that.</para> + +<para>Repositioning components in the Summary View is as simple +as dragging them to the new location you want them to be in. Click and +hold on the grey title area of the component and drag the component +to wherever you want it to be. Note that this positioning is done +compared to other components. So you can move the Mail component to be +below the to-do component in the view, but you can't place it in a specific +position. If you have only one component in your summary view, the only option +is to move it between the two columns of the view; two components can either +be two in one column or one in each column; and so on and so forth. Whenever +you are dragging a component, you will see a small preview box following your +mouse around showing you the component.</para> + +<screenshot> +<screeninfo>Rearranging &kontact;'s Summary View</screeninfo> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="summary-view-repositioning.png"/></imageobject> +<textobject> +<phrase>Rearranging &kontact;'s Summary View</phrase> +</textobject> +<caption> +<para> +Rearranging &kontact;'s Summary View +</para> +</caption> +</mediaobject> +</screenshot> +</sect1> + +</chapter> + + +<chapter id="configuration"> +<title>Configuring &kontact;</title> + +<sect1 id="main-config"> +<title>&kontact; Configuration Window</title> + +<para>When selecting the <guimenuitem>Configure &kontact;</guimenuitem> +action from the <guimenu>Settings</guimenu> menu, the &kontact; +configuration dialog is shown. It provides a list of the +configurations for all the active components of &kontact;. You can +click the <guilabel>-</guilabel> symbol next to the component names to +collapse their options so that you can view the options for the +component you are looking for. Selecting one of the configuration +options under a heading will bring up that configuration section on +the right.</para> + +<screenshot> +<screeninfo>&kontact;'s Configuration Window</screeninfo> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="configuration-main.png"/></imageobject> +<textobject> +<phrase>&kontact;'s Configuration Window</phrase> +</textobject> +<caption> +<para> +&kontact;'s Configuration Window +</para> +</caption> +</mediaobject> +</screenshot> + +<para>In addition, by clicking on the <guibutton>Configure...</guibutton> +button, you can bring up a dialog that will allow you to select which +components you want active from a list. +By checking the box next to the component title you select the +component to be put into the side bar and the summary view. The +component is loaded and its main view is shown in the main window when +clicking on its icon in the side pane for the first time. By +unchecking the check box the component is removed from the side pane and +summary view. Changes become effective by clicking the +<guibutton>Apply</guibutton> or <guibutton>OK</guibutton> +button.</para> + +<screenshot> +<screeninfo>&kontact;'s Select Components Window</screeninfo> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="configuration-components.png"/></imageobject> +<textobject> +<phrase>&kontact;'s Select Components Window</phrase> +</textobject> +<caption> +<para> +&kontact;'s Select Components Window +</para> +</caption> +</mediaobject> +</screenshot> + +<para>You can also configure individual components by activating the +component by clicking on the corresponding icon in the side pane of +the main window and then selecting the menu item +<guimenuitem>Configure <replaceable>application +name</replaceable></guimenuitem> from the <guimenu>Settings</guimenu> +menu.</para> + +<screenshot> +<screeninfo>&kontact; Settings Menu When KMail is Selected</screeninfo> +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="settings-menu-kmail.png"/> +</imageobject> +<textobject> +<phrase>&kontact; Settings Menu When KMail is Selected</phrase> +</textobject> +<caption> +<para> +&kontact; Settings Menu When KMail is Selected +</para> +</caption> +</mediaobject> +</screenshot> + +</sect1> + +<sect1 id="summary-view-config"> +<title>Configuring &kontact;'s Summary View</title> + +<para>When you select <guimenuitem>Configure Summary View...</guimenuitem> +from the &kontact; <guimenu>Settings</guimenu> menu (only available in +Summary View), a dialog pops up that allows you to select which summary +plugins &kontact; should show in its summary view. +Here is a brief list of the currently available plugins and what they do: +</para> + +<sect2 id="summary-view-config-calendar"> +<title>&kontact; Summary Plugins: Calendar</title> + +<para> +The <quote>Calendar</quote> plugin for &kontact;'s Summary View adds +an area in the view labeled <guilabel>Appointments</guilabel>. This +will display any appointments that currently apply. +</para> + +<screenshot> +<screeninfo>&kontact; Calendar Summary Plugin</screeninfo> +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="summary-view-calendar.png"/> +</imageobject> +<textobject> +<phrase>&kontact; Calendar Summary Plugin</phrase> +</textobject> +<caption> +<para> +&kontact; Calendar Summary Plugin +</para> +</caption> +</mediaobject> +</screenshot> +</sect2> + +<sect2 id="summary-view-config-contacts"> +<title>&kontact; Summary Plugins: Contacts</title> + +<para> +The <quote>Contacts</quote> plugin for &kontact;'s Summary View adds +an area in the view labeled <guilabel>Birthdays and +Anniversaries</guilabel> where birthdays and anniversaries of your +contacts are displayed (for contacts who have that information set in +their contact information; see the <ulink +url="help:/kaddressbook/index.html">&kaddressbook; +documentation</ulink> for more information on setting relevant contact +information). It contains the following information: +</para> + +<itemizedlist> +<listitem> + <para>Number of days from now when item will occur</para> +</listitem> +<listitem> + <para>Date of birth/anniversary</para> +</listitem> +<listitem> + <para>Name (Click on this to send an email, + right-click for the option to view the contact's + information)</para> +</listitem> +<listitem> + <para>Age/Anniversary Year</para> +</listitem> +</itemizedlist> + +<screenshot> +<screeninfo>&kontact; Contacts Summary Plugin</screeninfo> +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="summary-view-contacts.png"/> +</imageobject> +<textobject> +<phrase>&kontact; Contacts Summary Plugin</phrase> +</textobject> +<caption> +<para> +&kontact; Contacts Summary Plugin +</para> +</caption> +</mediaobject> +</screenshot> +</sect2> + +<sect2 id="summary-view-config-kpilot"> +<title>&kontact; Summary Plugins: KPilot</title> + +<para> +The <quote>KPilot</quote> plugin for &kontact;'s Summary View adds an +area in the view labeled <guilabel>KPilot Information</guilabel>. +This area contains a lot of information from KPilot, including: +</para> + +<itemizedlist> +<listitem> + <para>Last synchronization (with sync log)</para> +</listitem> +<listitem> + <para>User who last synchronized</para> +</listitem> +<listitem> + <para>Device last synchronized</para> +</listitem> +<listitem> + <para>Current status</para> +</listitem> +<listitem> + <para>Available conduits</para> +</listitem> +</itemizedlist> + +<screenshot> +<screeninfo>&kontact; KPilot Summary Plugin</screeninfo> +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="summary-view-kpilot.png"/> +</imageobject> +<textobject> +<phrase>&kontact; KPilot Summary Plugin</phrase> +</textobject> +<caption> +<para> +&kontact; KPilot Summary Plugin +</para> +</caption> +</mediaobject> +</screenshot> +</sect2> + +<sect2 id="summary-view-config-mail"> +<title>&kontact; Summary Plugins: Mail</title> + +<para> +The <quote>Mail</quote> plugin for &kontact;'s Summary View adds an +area in the view labeled <guilabel>New Messages</guilabel>. This area +is updated every time you receive new messages to inform you how many +of these messages there are and which folder they are in. +</para> + +<screenshot> +<screeninfo>&kontact; Mail Summary Plugin</screeninfo> +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="summary-view-mail.png"/> +</imageobject> +<textobject> +<phrase>&kontact; Mail Summary Plugin</phrase> +</textobject> +<caption> +<para> +&kontact; Mail Summary Plugin +</para> +</caption> +</mediaobject> +</screenshot> +</sect2> + +<sect2 id="summary-view-config-newsticker"> +<title>&kontact; Summary Plugins: NewsTicker</title> + +<para> +The <quote>NewsTicker</quote> plugin for &kontact;'s Summary View adds an +area in the view labeled <guilabel>News Feeds</guilabel>. +This area contains the latest news from the currently configured news +feeds. You can add and remove feeds in &kontact;'s Summary View +Configuration. Please note that as of &kde; 3.4, the more efficient +way of accessing RSS feed information is the new &akregator; application, +which provides notifications instead of requiring constant checking of +the Summary View to see if new articles have appeared. +</para> + +<screenshot> +<screeninfo>&kontact; NewsTicker Plugin</screeninfo> +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="summary-view-newsticker.png"/> +</imageobject> +<textobject> +<phrase>&kontact; NewsTicker Plugin</phrase> +</textobject> +<caption> +<para> + &kontact; NewsTicker Plugin +</para> +</caption> +</mediaobject> +</screenshot> +</sect2> + +<sect2 id="summary-view-config-notes"> +<title>&kontact; Summary Plugins: Notes</title> + +<para> +The <quote>Notes</quote> plugin for &kontact;'s Summary View adds an +area in the view labeled <guilabel>Notes</guilabel>. This area +displays all current notes' titles (titles default to the date/time +the note was created). Clicking on the title of a note will bring up +the Notes area. +</para> + +<screenshot> +<screeninfo>&kontact; Notes Summary Plugin</screeninfo> +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="summary-view-notes.png"/> +</imageobject> +<textobject> +<phrase>&kontact; Notes Summary Plugin</phrase> +</textobject> +<caption> +<para> +&kontact; Notes Summary Plugin +</para> +</caption> +</mediaobject> +</screenshot> +</sect2> + +<sect2 id="summary-view-config-todo-list"> +<title>&kontact; Summary Plugins: Todo List</title> + +<para> +The <quote>Todo List</quote> plugin for &kontact;'s Summary View adds +an area in the view labeled <guilabel>Todos</guilabel>. This area +contains all current todos, including ones that have been completed. +It displays the title of the todo, the percentage of completion, and +the current status of the todo. Note that you can purge all completed +todos via the &kontact; Todo List. Clicking on a todo's title will +currently do nothing. +</para> + +<screenshot> +<screeninfo>&kontact; Todo List Summary Plugin</screeninfo> +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="summary-view-todos.png"/> +</imageobject> +<textobject> +<phrase>&kontact; Todo List Summary Plugin</phrase> +</textobject> +<caption> +<para> +&kontact; Todo List Summary Plugin +</para> +</caption> +</mediaobject> +</screenshot> +</sect2> + +<sect2 id="summary-view-config-special-dates"> +<title>&kontact; Summary Plugins: Special Dates</title> + +<para> +The <quote>Special Dates</quote> plugin for &kontact;'s Summary View adds an +area in the view labeled <guilabel>Special Dates</guilabel>. +This area contains information based on the criteria selected in the +configuration area of the plugin in &kontact;'s Summary View configuration. +The <quote>Special Dates</quote> plugin is especially useful because it can +display birthdays, anniversaries, holidays, and special occasions from both +the calendar and the contact list in one place. +</para> + +<screenshot> +<screeninfo>&kontact; Special Dates Plugin</screeninfo> +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="summary-view-special-dates.png"/> +</imageobject> +<textobject> +<phrase>&kontact; Special Dates Plugin</phrase> +</textobject> +<caption> +<para> + &kontact; Special Dates Plugin +</para> +</caption> +</mediaobject> +</screenshot> +</sect2> + +<sect2 id="summary-view-config-weather"> +<title>&kontact; Summary Plugins: Weather</title> + +<para> +The <quote>Weather</quote> plugin for &kontact;'s Summary View adds an +area in the view labeled <guilabel>Weather Information</guilabel>. +This area contains the information for currently configured weather +locations. For more information about configuring KWeather, the +weather reporter used as a plugin within &kontact;, see the <ulink +url="help:/kweather/configuring-kweather.html"> KWeather +documentation</ulink>. +</para> + +<screenshot> +<screeninfo>&kontact; Weather Summary Plugin</screeninfo> +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="summary-view-weather.png"/> +</imageobject> +<textobject> +<phrase>&kontact; Weather Summary Plugin</phrase> +</textobject> +<caption> +<para> +&kontact; Weather Summary Plugin +</para> +</caption> +</mediaobject> +</screenshot> +</sect2> + +</sect1> +<sect1 id="kontact-configure-profiles"> +<title>&kontact; Profiles</title> +<para>&kontact;'s profile support makes it possible to load and save user settings in profiles. +The settings stored in the profile include typical Look&Feel related options such as app-specific color schemes, icon sets, toolbar layout and application defaults. Personal information, e.g. accounts and identities are not stored in profiles. +Two default profiles are provided by Kontact: "&kontact; Style", which contains the default &kontact; settings, and "Outlook Style", adapting &kontact; to Microsoft Outlook Look&Feel. +The user can adapt existing profiles, create new profiles from his current settings, and import and export profiles. To manage profiles, choose "Configure Profiles" from the "Settings" menu. +</para> +</sect1> +</chapter> + + +<chapter id="command-line"> +<title>&kontact; On the Command Line</title> + +<para>&kontact; has several command line arguments +that can be used for certain actions.</para> + +<para>First of all, &kontact; supports command line arguments +that all KDE/Qt applications support. You can get a full list of +these by typing: +</para> + +<para> +<prompt>%</prompt> <command>kontact --help-all</command> +</para> + +<para>&kontact; also supports several command line arguments +specific to it.</para> + +<sect1 id="command-line-arguments"> +<title>Command Line Arguments</title> + +<sect2 id="command-line-module"> +<title>Module-related Arguments</title> + +<para>To get a list of available &kontact; modules, you can type:</para> + +<para> +<prompt>%</prompt> <command>kontact --list</command> +</para> + +<para>Then, to start &kontact; with a module active, type:</para> + +<para> +<prompt>%</prompt> <command>kontact --module <replaceable>moduleName</replaceable></command> +</para> + +<para>Where <replaceable>moduleName</replaceable> is one of the modules obtained using the +previous command.</para> + +</sect2> + +</sect1> + +</chapter> + + +<chapter id="technology"> +<title>Under The Hood</title> + +<para>&kontact; makes extensive use of several &kde; key technologies, most +notably KParts and &DCOP;.</para> + +<para>The &GUI; integration of the components is done by plugins +providing KParts versions of the applications. This only needs a thin +additional layer on top of the already existing code of the +stand-alone applications.</para> + +<para>For communication between the components &DCOP; is used. This +has the nice characteristic that it is completely transparent to +whether the application is run stand-alone or embedded as KPart into +&kontact;. When running inside of &kontact; an efficient in-process +mode of &DCOP; is used.</para> + +</chapter> + + +<chapter id="credits"> +<title>Credits and License</title> + +<para>&kontact;</para> + +<para>Program copyright 2004, The &kde; Developers</para> + +<para>Contributors:</para> + +<itemizedlist> +<listitem><para>Cornelius Schumacher <email>schumacher@kde.org</email></para> +</listitem> +<listitem><para>Daniel Molkentin <email>molkentin@kde.org</email></para> +</listitem> +<listitem><para>Don Sanders <email>sanders@kde.org</email></para> +</listitem> +<listitem><para>Tobias König <email>tokoe@kde.org</email></para> +</listitem> +<listitem><para>Matthis Hölzer-Klüpfel <email>mhk@kde.org</email>, the +original author of the &kontact; framework.</para> +</listitem> + +<listitem><para>All the valued developers of the applications &kontact; is +integrating. They did almost all the work.</para> +</listitem> +</itemizedlist> + +<para>Documentation copyright 2004-2005</para> + +<para>Contributors: + +<itemizedlist> +<listitem><para>Cornelius Schumacher <email>schumacher@kde.org</email></para> +</listitem> +<listitem><para>Antonio Salazar <email>savedfastcool@gmail.com</email></para> +</listitem> +<listitem><para>Daniel Molkentin <email>molkentin@kde.org</email></para> +</listitem> + +<listitem><para>All the members of the KDE documentation list who +assisted with markup and style issues.</para> +</listitem> +</itemizedlist> +</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +<para>&kontact; homepage is at <ulink +url="http://kontact.kde.org">http://kontact.kde.org</ulink></para> + + + + +&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/kontact/kaddressbook-sidebar-icon.png b/doc/kontact/kaddressbook-sidebar-icon.png Binary files differnew file mode 100644 index 000000000..4240f41f9 --- /dev/null +++ b/doc/kontact/kaddressbook-sidebar-icon.png diff --git a/doc/kontact/main-view.png b/doc/kontact/main-view.png Binary files differnew file mode 100644 index 000000000..eca59e7f9 --- /dev/null +++ b/doc/kontact/main-view.png diff --git a/doc/kontact/menu-bar-kmail.png b/doc/kontact/menu-bar-kmail.png Binary files differnew file mode 100644 index 000000000..d9c5e8c38 --- /dev/null +++ b/doc/kontact/menu-bar-kmail.png diff --git a/doc/kontact/menu-bar-korganizer.png b/doc/kontact/menu-bar-korganizer.png Binary files differnew file mode 100644 index 000000000..0b161b3ca --- /dev/null +++ b/doc/kontact/menu-bar-korganizer.png diff --git a/doc/kontact/menu-bar-summary.png b/doc/kontact/menu-bar-summary.png Binary files differnew file mode 100644 index 000000000..da4a99d9d --- /dev/null +++ b/doc/kontact/menu-bar-summary.png diff --git a/doc/kontact/new-menu.png b/doc/kontact/new-menu.png Binary files differnew file mode 100644 index 000000000..24531be8f --- /dev/null +++ b/doc/kontact/new-menu.png diff --git a/doc/kontact/settings-menu-kmail.png b/doc/kontact/settings-menu-kmail.png Binary files differnew file mode 100644 index 000000000..5608a1f02 --- /dev/null +++ b/doc/kontact/settings-menu-kmail.png diff --git a/doc/kontact/side-pane.png b/doc/kontact/side-pane.png Binary files differnew file mode 100644 index 000000000..d57e123c3 --- /dev/null +++ b/doc/kontact/side-pane.png diff --git a/doc/kontact/summary-view-calendar.png b/doc/kontact/summary-view-calendar.png Binary files differnew file mode 100644 index 000000000..ba3e6bfb0 --- /dev/null +++ b/doc/kontact/summary-view-calendar.png diff --git a/doc/kontact/summary-view-contacts.png b/doc/kontact/summary-view-contacts.png Binary files differnew file mode 100644 index 000000000..c9f925431 --- /dev/null +++ b/doc/kontact/summary-view-contacts.png diff --git a/doc/kontact/summary-view-kpilot.png b/doc/kontact/summary-view-kpilot.png Binary files differnew file mode 100644 index 000000000..b970e0125 --- /dev/null +++ b/doc/kontact/summary-view-kpilot.png diff --git a/doc/kontact/summary-view-mail.png b/doc/kontact/summary-view-mail.png Binary files differnew file mode 100644 index 000000000..71216ef05 --- /dev/null +++ b/doc/kontact/summary-view-mail.png diff --git a/doc/kontact/summary-view-newsticker.png b/doc/kontact/summary-view-newsticker.png Binary files differnew file mode 100644 index 000000000..ebbb7310c --- /dev/null +++ b/doc/kontact/summary-view-newsticker.png diff --git a/doc/kontact/summary-view-notes.png b/doc/kontact/summary-view-notes.png Binary files differnew file mode 100644 index 000000000..de3f72ee0 --- /dev/null +++ b/doc/kontact/summary-view-notes.png diff --git a/doc/kontact/summary-view-repositioning.png b/doc/kontact/summary-view-repositioning.png Binary files differnew file mode 100644 index 000000000..5a494170d --- /dev/null +++ b/doc/kontact/summary-view-repositioning.png diff --git a/doc/kontact/summary-view-todos.png b/doc/kontact/summary-view-todos.png Binary files differnew file mode 100644 index 000000000..79adb3712 --- /dev/null +++ b/doc/kontact/summary-view-todos.png diff --git a/doc/kontact/summary-view-weather.png b/doc/kontact/summary-view-weather.png Binary files differnew file mode 100644 index 000000000..3100fbb96 --- /dev/null +++ b/doc/kontact/summary-view-weather.png diff --git a/doc/kontact/summary-view.png b/doc/kontact/summary-view.png Binary files differnew file mode 100644 index 000000000..d539feeac --- /dev/null +++ b/doc/kontact/summary-view.png diff --git a/doc/kontact/todo-list-sidebar-icon.png b/doc/kontact/todo-list-sidebar-icon.png Binary files differnew file mode 100644 index 000000000..f9a7176e1 --- /dev/null +++ b/doc/kontact/todo-list-sidebar-icon.png diff --git a/doc/korganizer/Makefile.am b/doc/korganizer/Makefile.am new file mode 100644 index 000000000..171f575ce --- /dev/null +++ b/doc/korganizer/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/korganizer/event-attachments.png b/doc/korganizer/event-attachments.png Binary files differnew file mode 100644 index 000000000..9f3d6aced --- /dev/null +++ b/doc/korganizer/event-attachments.png diff --git a/doc/korganizer/event-attendees.png b/doc/korganizer/event-attendees.png Binary files differnew file mode 100644 index 000000000..76046352b --- /dev/null +++ b/doc/korganizer/event-attendees.png diff --git a/doc/korganizer/event-freebusy.png b/doc/korganizer/event-freebusy.png Binary files differnew file mode 100644 index 000000000..4e83859be --- /dev/null +++ b/doc/korganizer/event-freebusy.png diff --git a/doc/korganizer/event-general.png b/doc/korganizer/event-general.png Binary files differnew file mode 100644 index 000000000..15e91eac7 --- /dev/null +++ b/doc/korganizer/event-general.png diff --git a/doc/korganizer/event-recurrence.png b/doc/korganizer/event-recurrence.png Binary files differnew file mode 100644 index 000000000..f157f6a7e --- /dev/null +++ b/doc/korganizer/event-recurrence.png diff --git a/doc/korganizer/groupevent.png b/doc/korganizer/groupevent.png Binary files differnew file mode 100644 index 000000000..31b6f3399 --- /dev/null +++ b/doc/korganizer/groupevent.png diff --git a/doc/korganizer/i_actions_newevent.png b/doc/korganizer/i_actions_newevent.png Binary files differnew file mode 100644 index 000000000..22aa13e8f --- /dev/null +++ b/doc/korganizer/i_actions_newevent.png diff --git a/doc/korganizer/i_actions_newtodo.png b/doc/korganizer/i_actions_newtodo.png Binary files differnew file mode 100644 index 000000000..5d337346b --- /dev/null +++ b/doc/korganizer/i_actions_newtodo.png diff --git a/doc/korganizer/i_copy.png b/doc/korganizer/i_copy.png Binary files differnew file mode 100644 index 000000000..cfa9cb431 --- /dev/null +++ b/doc/korganizer/i_copy.png diff --git a/doc/korganizer/i_cut.png b/doc/korganizer/i_cut.png Binary files differnew file mode 100644 index 000000000..79d2dcae3 --- /dev/null +++ b/doc/korganizer/i_cut.png diff --git a/doc/korganizer/i_edit_delete.png b/doc/korganizer/i_edit_delete.png Binary files differnew file mode 100644 index 000000000..6fb193f06 --- /dev/null +++ b/doc/korganizer/i_edit_delete.png diff --git a/doc/korganizer/i_edit_find.png b/doc/korganizer/i_edit_find.png Binary files differnew file mode 100644 index 000000000..91f6eb656 --- /dev/null +++ b/doc/korganizer/i_edit_find.png diff --git a/doc/korganizer/i_edit_redo.png b/doc/korganizer/i_edit_redo.png Binary files differnew file mode 100644 index 000000000..a424839e7 --- /dev/null +++ b/doc/korganizer/i_edit_redo.png diff --git a/doc/korganizer/i_edit_undo.png b/doc/korganizer/i_edit_undo.png Binary files differnew file mode 100644 index 000000000..e5f15b2f3 --- /dev/null +++ b/doc/korganizer/i_edit_undo.png diff --git a/doc/korganizer/i_file_close.png b/doc/korganizer/i_file_close.png Binary files differnew file mode 100644 index 000000000..8acc84d11 --- /dev/null +++ b/doc/korganizer/i_file_close.png diff --git a/doc/korganizer/i_file_new.png b/doc/korganizer/i_file_new.png Binary files differnew file mode 100644 index 000000000..6e838b325 --- /dev/null +++ b/doc/korganizer/i_file_new.png diff --git a/doc/korganizer/i_file_open.png b/doc/korganizer/i_file_open.png Binary files differnew file mode 100644 index 000000000..503a00459 --- /dev/null +++ b/doc/korganizer/i_file_open.png diff --git a/doc/korganizer/i_file_print.png b/doc/korganizer/i_file_print.png Binary files differnew file mode 100644 index 000000000..d554b554f --- /dev/null +++ b/doc/korganizer/i_file_print.png diff --git a/doc/korganizer/i_file_quit.png b/doc/korganizer/i_file_quit.png Binary files differnew file mode 100644 index 000000000..744588794 --- /dev/null +++ b/doc/korganizer/i_file_quit.png diff --git a/doc/korganizer/i_file_revert.png b/doc/korganizer/i_file_revert.png Binary files differnew file mode 100644 index 000000000..5111dd0b2 --- /dev/null +++ b/doc/korganizer/i_file_revert.png diff --git a/doc/korganizer/i_file_save.png b/doc/korganizer/i_file_save.png Binary files differnew file mode 100644 index 000000000..dd00abd16 --- /dev/null +++ b/doc/korganizer/i_file_save.png diff --git a/doc/korganizer/i_file_saveas.png b/doc/korganizer/i_file_saveas.png Binary files differnew file mode 100644 index 000000000..61a080ecd --- /dev/null +++ b/doc/korganizer/i_file_saveas.png diff --git a/doc/korganizer/i_go_backward.png b/doc/korganizer/i_go_backward.png Binary files differnew file mode 100644 index 000000000..60caccf07 --- /dev/null +++ b/doc/korganizer/i_go_backward.png diff --git a/doc/korganizer/i_go_forward.png b/doc/korganizer/i_go_forward.png Binary files differnew file mode 100644 index 000000000..d3e6d1e59 --- /dev/null +++ b/doc/korganizer/i_go_forward.png diff --git a/doc/korganizer/i_go_to_today.png b/doc/korganizer/i_go_to_today.png Binary files differnew file mode 100644 index 000000000..2a842d2ec --- /dev/null +++ b/doc/korganizer/i_go_to_today.png diff --git a/doc/korganizer/i_paste.png b/doc/korganizer/i_paste.png Binary files differnew file mode 100644 index 000000000..a192060bd --- /dev/null +++ b/doc/korganizer/i_paste.png diff --git a/doc/korganizer/i_settings_prefs.png b/doc/korganizer/i_settings_prefs.png Binary files differnew file mode 100644 index 000000000..11415643f --- /dev/null +++ b/doc/korganizer/i_settings_prefs.png diff --git a/doc/korganizer/i_view_day.png b/doc/korganizer/i_view_day.png Binary files differnew file mode 100644 index 000000000..97bc5cdf3 --- /dev/null +++ b/doc/korganizer/i_view_day.png diff --git a/doc/korganizer/i_view_journal.png b/doc/korganizer/i_view_journal.png Binary files differnew file mode 100644 index 000000000..0fe1dd10d --- /dev/null +++ b/doc/korganizer/i_view_journal.png diff --git a/doc/korganizer/i_view_list.png b/doc/korganizer/i_view_list.png Binary files differnew file mode 100644 index 000000000..fd1eec19e --- /dev/null +++ b/doc/korganizer/i_view_list.png diff --git a/doc/korganizer/i_view_month.png b/doc/korganizer/i_view_month.png Binary files differnew file mode 100644 index 000000000..3c1a0b177 --- /dev/null +++ b/doc/korganizer/i_view_month.png diff --git a/doc/korganizer/i_view_todo_list.png b/doc/korganizer/i_view_todo_list.png Binary files differnew file mode 100644 index 000000000..cec783150 --- /dev/null +++ b/doc/korganizer/i_view_todo_list.png diff --git a/doc/korganizer/i_view_week.png b/doc/korganizer/i_view_week.png Binary files differnew file mode 100644 index 000000000..0d0908b71 --- /dev/null +++ b/doc/korganizer/i_view_week.png diff --git a/doc/korganizer/i_view_whatsnext.png b/doc/korganizer/i_view_whatsnext.png Binary files differnew file mode 100644 index 000000000..02577bb80 --- /dev/null +++ b/doc/korganizer/i_view_whatsnext.png diff --git a/doc/korganizer/i_view_work_week.png b/doc/korganizer/i_view_work_week.png Binary files differnew file mode 100644 index 000000000..0e02d4c4e --- /dev/null +++ b/doc/korganizer/i_view_work_week.png diff --git a/doc/korganizer/i_view_xdays.png b/doc/korganizer/i_view_xdays.png Binary files differnew file mode 100644 index 000000000..441e2f802 --- /dev/null +++ b/doc/korganizer/i_view_xdays.png diff --git a/doc/korganizer/index.docbook b/doc/korganizer/index.docbook new file mode 100644 index 000000000..a0398ed26 --- /dev/null +++ b/doc/korganizer/index.docbook @@ -0,0 +1,4982 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd" [ + <!ENTITY kappname "&korganizer;"> + <!ENTITY package "kdepim"> + <!ENTITY plugins-chapter SYSTEM "plugins-chapter.docbook"> + <!ENTITY exchange-plugin-workshop SYSTEM "exchange-plugin.docbook"> + <!ENTITY group-scheduling-workshop SYSTEM "group-scheduling.docbook"> + <!ENTITY outlook-to-vcalendar-workshop SYSTEM "outlook-to-vcalendar.docbook"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> + +<book id="korganizer" lang="&language;"> + +<bookinfo> + +<title>The &korganizer; Handbook</title> + +<authorgroup> + +<author> +<firstname>Carlos</firstname> +<othername>Leonhard</othername> +<surname>Woelz</surname> +<affiliation><address><email>carloswoelz@imap-mail.com</email></address></affiliation> +</author> + +<author> +<firstname>Milos</firstname> +<surname>Prudek</surname> +</author> + +<author> +<firstname>Paul</firstname> +<othername>E.</othername> +<surname>Ahlquist</surname> +<lineage>Jr.</lineage> +<affiliation><address>&Paul.E.Ahlquist.Jr.mail;</address></affiliation> +</author> + +<author> +<firstname>Jürgen</firstname> +<surname>Nagel</surname> +<affiliation><address><email>juergen.nagel@student.fh-reutlingen.de</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> + +<othercredit role="developer"> +<firstname>Reinhold</firstname> +<surname>Kainhofer</surname> +<affiliation><address><email>reinhold@kainhofer.com</email></address></affiliation> +<contrib>Developer</contrib> +</othercredit> + +<othercredit role="developer"> +<firstname>Cornelius</firstname> +<surname>Schumacher</surname> +<affiliation><address>&Cornelius.Schumacher.mail;</address></affiliation> +<contrib>Developer</contrib> +</othercredit> + +<othercredit role="developer"> +<firstname>Preston</firstname> +<surname>Brown</surname> +<affiliation><address>&Preston.Brown.mail;</address></affiliation> +<contrib>Developer</contrib> +</othercredit> + +<othercredit role="reviewer"> +<firstname>Lauri</firstname> +<surname>Watts</surname> +<affiliation><address>&Lauri.Watts.mail;</address></affiliation> +<contrib>Reviewer</contrib> +</othercredit> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + + + +<copyright> +<year>2000</year><holder>&Milos.Prudek;</holder> +</copyright> + +<copyright> +<year>2001</year> +<holder>&Paul.E.Ahlquist.Jr;</holder> +</copyright> + +<copyright> +<year>2004</year> +<holder>Jürgen Nagel</holder> +</copyright> + +<copyright> +<year>2005</year> +<holder>Carlos Leonhard Woelz</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2005-08-29</date> +<releaseinfo>3.00.00</releaseinfo> + +<abstract><para>&korganizer; is an easy to use personal information manager +(<acronym>PIM</acronym>). You can write journal entries, schedule appointments, +events, and to-dos. &korganizer; will remind you about pending tasks, and +help you keep your schedule. </para></abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KOrganizer</keyword> +<keyword>kdepim</keyword> +<keyword>manager</keyword> +<keyword>time</keyword> +<keyword>schedule</keyword> +<keyword>alarm</keyword> +<keyword>appointment</keyword> +<keyword>event</keyword> +<keyword>jornal</keyword> +<keyword>to-do</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&korganizer; is an intuitive and easy to use personal information manager +(<abbrev>PIM</abbrev>). You can schedule appointments, events, create +to-dos and write journal entries. &korganizer; will remind you about +pending tasks, record your occurrences, experiences, and reflections and help +you keep your schedule.</para> + +<para>But &korganizer; is not only about your personal calendar, it can +help you to interact with your colleagues and friends too. With &korganizer;, +you can publish a calendar as a web page, invite anyone with an email address +to an event and process responses, share a calendar (using a groupware +server or simply a file over the network), and share events (⪚ +the schedule of a championship or a conference), using the get hot new stuff +framework. &korganizer; is based on open standards, and works with +many different group scheduling servers, giving you the control over your +information and the freedom to choose the best solutions. +</para> + +<para>&korganizer; is also the calendar, journal and to-do component of +&kontact;, offering you an integrated solution for your +communication and information management needs: email, notes, contacts +management, news reader, synchronization with portable devices, and news feeds +reader. Even if you don't use it inside &kontact;, &korganizer; is +integrated with the other &kde; <acronym>PIM</acronym> applications. +For instance, you can configure it to show birthdays from &kaddressbook; in your +agenda, use &kmail; to send and receive invitations, &etc;</para> + +<para>Main features of &korganizer;:</para> +<para><itemizedlist> +<listitem><para>Create To-dos, schedule events, and write journal entries.</para></listitem> +<listitem><para>Organize your events and to-dos by grouping the related items in categories.</para></listitem> +<listitem><para>Highlight categories with colors.</para></listitem> +<listitem><para>Open multiple calendars, and seamless view and edit them.</para></listitem> +<listitem><para>Reschedule your events by drag-and-drop.</para></listitem> +<listitem><para>Generate recurring events easily.</para></listitem> +<listitem><para>Organize or attend events using the group scheduling features.</para></listitem> +<listitem><para>Choose among the multiple supported groupware servers.</para></listitem> +<listitem><para>vCalendar and iCalendar (open standards) native support.</para></listitem> +<listitem><para>Calendar merging and import.</para></listitem> +<listitem><para>Synchronize your data with &PalmOS; devices.</para></listitem> +<listitem><para>Drag-and-drop between open calendars.</para></listitem> +<listitem><para>Embedding collaboration with &konqueror;.</para></listitem> +<listitem><para>Customizable icon sets.</para></listitem> +<listitem><para>Drag-and-drop tool panels.</para></listitem> +<listitem><para>Much more...</para></listitem> +</itemizedlist></para> + + +<para>Now take a <link linkend="five-minute-course">Five-minute fly-over +course</link> of &korganizer;, or delve into <link +linkend="managing-data">the documentation</link>!</para> + +</chapter> + +<chapter id="five-minute-course"> +<title>Five-minute Fly-over Course of &korganizer;</title> +<subtitle> (for the experienced and for the impatient)</subtitle> + +<para>Pressed for time? Let's kick you started with a fast, hands-on overview +of &korganizer;!</para> + +<para>If you ever worked with a personal information program before, you'll be +right at home with &korganizer;. You can enter new events, reschedule existing +events, assign categories to your events, devise new categories, enter and +modify lists of attendees and their roles, email event invitations +automatically and exchange data with other &korganizer; calendars, create +to-dos and write journal entries.</para> + +<para>This course assumes that you know how to work with the &kde;, and that +you prefer to explore on your own. Only the basic functions of &korganizer; +are covered here.</para> + +<sect1 id="course-entering-events"> +<title>Entering Events</title> + +<procedure> +<step><para>Click the <guiicon><inlinemediaobject><imageobject> +<imagedata fileref="i_view_day.png" format="PNG"/></imageobject> +</inlinemediaobject></guiicon><guibutton>Day View</guibutton> toolbar button +or choose the <menuchoice><guimenu>View</guimenu> +<guimenuitem>Day</guimenuitem></menuchoice> menu item. +This will bring up the <link linkend="agenda-view"><guilabel>Day View</guilabel> +</link>.</para></step> + +<step><para>Click on the desired date in the +<link linkend="glossary" endterm="gloss-date-navigator">Date Navigator</link>. +</para></step> + +<step><para>Select the text area beside the desired +hour in the main panel that reflects the time of the event. Double click +this area, or just start typing the title of the event to open the +<guilabel>New Event</guilabel> dialog.</para></step> + +<step><para><link linkend="entering-data-events">Enter event details</link>. Use tabs <guilabel>General</guilabel>, +<guilabel>Recurrence</guilabel>, <guilabel>Attendees</guilabel>, +<guilabel>Free/Busy</guilabel> and <guilabel>Attachments</guilabel> to move +around the dialog and access all the event's characteristics.</para></step> + +<step><para>Press <guibutton>OK</guibutton> to save the +event.</para></step> +</procedure> +</sect1> + +<sect1 id="course-entering-todos"> +<title>Entering To-dos</title> + +<procedure> +<step><para>Select the <menuchoice><guimenu>Actions</guimenu> +<guimenuitem>New To-do...</guimenuitem></menuchoice> menu item to open the +<guilabel>New To-do</guilabel> dialog.</para></step> + +<step><para><link linkend="entering-data-to-do">Enter the to-do details</link>. +Use tabs <guilabel>General</guilabel>, +<guilabel>Attendees</guilabel>, <guilabel>Recurrence</guilabel> and +<guilabel>Attachments</guilabel> to move around the dialog.</para></step> + +<step><para>Press <guibutton>OK</guibutton> to save the +to-do.</para></step> +</procedure> + +</sect1> + +<sect1 id="course-entering-journals"> +<title>Adding Journal Entries</title> + +<procedure> + +<step><para>Select the <guiicon><inlinemediaobject><imageobject> +<imagedata fileref="i_view_journal.png" format="PNG"/></imageobject> +</inlinemediaobject></guiicon><menuchoice><guimenu>View</guimenu> +<guimenuitem>Journal</guimenuitem></menuchoice> menu item to open the +<link linkend="journal-view"><guilabel>Journal</guilabel> main +view</link>.</para></step> + +<step><para>Click the <guilabel>Add Journal Entry</guilabel> link.</para></step> + +<step><para>Enter journal entry title and text.</para></step> + +</procedure> + +</sect1> + +<sect1 id="course-rescheduling-events"> +<title>Rescheduling Events</title> + +<para>Rescheduling events is a simple drag-and-drop operation:</para> + +<procedure> +<step><para>Using the +<link linkend="glossary" endterm="gloss-date-navigator">Date Navigator</link> +go to the date of the event that you want to reschedule.</para></step> + +<step><para>You should choose an appropriate <link +linkend="reference-menus-view">view</link> before beginning this operation. +Only the <link linkend="agenda-view"><guilabel>agenda view</guilabel> +</link> (day, work week and week views) shows individual hours and are suitable +for rescheduling exactly-timed events (appointments), while the Month view +only shows days. Therefore the Month view is most suitable for long-time +events like holidays.</para></step> + +<step><para>To display the week view, press the +<guiicon><inlinemediaobject><imageobject> +<imagedata fileref="i_view_week.png" format="PNG"/></imageobject> +</inlinemediaobject></guiicon><guibutton>Week View</guibutton> toolbar button, +or choose the <menuchoice><guimenu>View</guimenu> +<guimenuitem>Week</guimenuitem></menuchoice> menu item. +</para></step> + +<step><para>Drag and drop the event to the new date and time +location.</para></step> + +</procedure> + +<para>If you wish to reschedule more precisely, double-click the event and +change the start and end time using the drop down menus that divide the day +into quarter hours. If that is not precision enough, you can enter the +desired time directly.</para> + +</sect1> +<sect1 id="course-rescheduling-todos"> +<title>Rescheduling or Editing To-dos</title> + +<para>You should choose an appropriate <link +linkend="reference-menus-view">view</link> before beginning this operation. +Only the <link linkend="list-view"><guiicon><inlinemediaobject><imageobject> +<imagedata fileref="i_view_list.png" format="PNG"/></imageobject> +</inlinemediaobject></guiicon><guilabel>list view</guilabel> +</link>, <link linkend="todo-view"><guiicon><inlinemediaobject><imageobject> +<imagedata fileref="i_view_todo_list.png" format="PNG"/></imageobject> +</inlinemediaobject></guiicon><guilabel>to-do list view</guilabel> +</link> and <link linkend="description-view">the to-do view sidebar component +</link> show to-dos which do not have a due date.</para> + +<para>To display the to-do list view, press the +<guiicon><inlinemediaobject><imageobject> +<imagedata fileref="i_view_todo_list.png" format="PNG"/></imageobject> +</inlinemediaobject></guiicon><guibutton>To-do List View</guibutton> toolbar button, +or choose the <menuchoice><guimenu>View</guimenu> +<guimenuitem>To-do List</guimenuitem></menuchoice> menu item. +</para> + +<para>To reschedule a to-do, right click it. +This will bring up a context menu. Choose the <guimenuitem>Copy to</guimenuitem> or +<guimenuitem>Move to</guimenuitem> menu items and select the new date from the calendar +now appearing. The to-do is now copied or moved to the selected date. +Alternatively, if the main panel holds a <guilabel>To-do List View</guilabel>, +just right click the column <guilabel>Due Date</guilabel>. A calender will +appear instantly, allowing you to set the new due date.</para> + +<para>To <link linkend="entering-data-to-do">edit a to-do</link>, right click it and choose the +<guimenuitem>Edit...</guimenuitem> menu item.</para> + +</sect1> + +<sect1 id="course-conclusion"> +<title>Conclusion</title> + +<para>This five-minute course covered only the basic operation of &korganizer;. +Now you should go on and read the rest of this manual to unleash the full +power of &korganizer;'s capabilities. But if you don't feel like it, you +should at least skip through the <link linkend="faq">&FAQ;</link>.</para> + +</sect1> + +</chapter> + + +<chapter id="managing-data"> +<title>Importing, Exporting, and Managing Calendars</title> + +<para>&korganizer; can store (and retrieve) events, journals entries +and to-dos using various methods, and to different locations. +Each of these locations is called a <firstterm>calendar resource</firstterm>. +</para> + +<para>&korganizer; supports calendar files based on standards such as +iCalendar and vCalendar natively (adding them as new resources), but you can +import the data (merge) into an existing resource and open the file in a new +window too. Importing files in the format used by the old +<application>ical</application> application is also supported.</para> + +<para>You can export your data as a web page, as an iCalendar or +vCalendar file. These files are supported by most scheduling applications. +The web page can be used to publish your calendar and to-dos list in the +web or in the local network.</para> + +<para>If you have a calendar containing events of public interest, such as +a conference or championship schedule, you can upload it using the +<link linkend="managing-get-hot-new-stuff">get hot new stuff</link> framework. +You can use the same framework to check if there are events worth downloading. +</para> + +<para>In this chapter, we will explain how to manage your calendar, using the +resources, import and export actions and the get hot new stuff scheme.</para> + +<sect1 id="managing-resources"> +<title>Calendar Resources</title> + +<para>&korganizer; uses a local file, usually +<filename>$KDEHOME/share/apps/korganizer/std.ics</filename>, +as its default resource. But this is not your only option: there are several +other resources you can add: groupware servers, journal entries as blogs, +network files, &etc;. If you use more than one resource, &korganizer; +<link linkend="config-main-personal">can be configured to use the default +resource or ask which resource to use</link> when saving new events, to-dos or +journal entries. &korganizer; will seamlessly merge the items from +two or more resources in the <link linkend="description-view">views</link>. +</para> + +<para>The default resource is a good choice for many use cases, but you may +want to use another resource, especially if you use a supported groupware +server. Please ask the server administrator for the information required to +configure the groupware resource, including free/busy information publishing +and retrieving. Access to free/busy information allows an event organizer to +take the attendee's calendar in consideration when adding him to the the event's +attendee list.</para> + +<note><para>Besides calendar storage, groupware servers typically offer contacts, +mail and <link linkend="glossary" endterm="gloss-freebusy">free/busy +information</link> storage. Therefore, some of the resources discussed here +may be related to other resources from &kmail; and &kaddressbook; (the mail and +contacts components of &kontact;), or to the +<link linkend="config-main-free-busy">free/busy settings in the main +configuration</link>.</para> +<para>Please note that &korganizer; +<link linkend="group-scheduling">group scheduling</link> communication is +based on a peer to peer email standard. This means that you do not need a +groupware server to use it!</para></note> + +<screenshot id="screenshot-resources"> +<screeninfo>A screenshot of &korganizer;'s Resource View Sidebar</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="korganizer-resource.png" format="PNG"/></imageobject> +<textobject><phrase>A screenshot of &korganizer;'s Resource View Sidebar</phrase></textobject> +<caption><para>A screenshot of &korganizer;'s Resource View Sidebar</para></caption> +</mediaobject> +</screenshot> + +<procedure id="procedure-add-resource"> +<title>Adding a New &korganizer; Resource</title> + +<step><para>If the resource view is not available on &korganizer;'s sidebar, +choose the <menuchoice><guimenu>Settings</guimenu> +<guisubmenu>Sidebar</guisubmenu><guimenuitem>Show Resource +View</guimenuitem></menuchoice> menu item to display it. +</para></step> + +<step><para>If the resource buttons are not displayed on the resource viewer, +choose the <menuchoice><guimenu>Settings</guimenu><guisubmenu>Sidebar</guisubmenu> +<guimenuitem>Show Resource Buttons</guimenuitem></menuchoice> menu item to +display them.</para></step> + +<step><para>Press the <guilabel>Add...</guilabel> button to add new resources to +the list of available resources.</para></step> + +<step><para>Check or uncheck the resource box to enable or +disable it.</para></step> + +<step><para>Later, if you want to edit or delete a resource, select it on the +list and press <guilabel>Delete</guilabel> to remove it or +<guilabel>Edit...</guilabel> to modify it.</para></step> + +</procedure> + +<para>Alternatively, you can configure the &korganizer; resources (plus all +other &kde; resources), in the &kcontrolcenter;, using the <guilabel>&kde; +Resources</guilabel> configuration module.</para> + +<para>Among the existing resources, you can find:</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Birthdays from &kaddressbook;</guilabel></term> +<listitem><para>Add this resource to view birthdays from contacts in &kaddressbook; +in your calendar. The birthday appears in your calendar as a read only event and +without associated time.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Journal Entries as Blogs on Server</guilabel></term> +<listitem><para>Add this resource to be able to read your blogs as journal entries, +directly from blog servers, such as blogger and drupal.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Bugzilla To-do List</guilabel></term> +<listitem><para>Add this resource to load bugzilla open bugs as to-dos. +This resource is based on the &kbugbuster; application, and uses its bug cache +information. Bugzilla is an open source bug tracking system.</para> + +<para>If you are a developer working on a project that uses bugzilla, you can +use this resource to view as to-dos the open bugs of the applications or +libraries you are interested in (they are called <quote>products</quote> and / or <quote>components</quote> in bugzilla). This resource is available as part of +the &kde; Software Development kit. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>&XML; Feature Plan</guilabel></term> +<listitem><para>Add this resource to load a &XML; Feature Plan as to-dos. +The &XML; Feature Plan is a scheme designed to document the new features of +future software releases. It was designed to fit the &kde; release schedule +needs, but can be helpful for any software project. The information from the +&XML; file can be used to control feature freezes, to report the new +features of new release or the status of the new features of a future release. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Calendar in Local File</guilabel></term> +<listitem><para>Add this resource to be able to save (and load) your events, +to-dos and journal entries to a local file. The file can be in the iCalendar or +in the vCalendar standard format. &korganizer; uses this resource by default, +storing your calendar information under +<filename>$KDEHOME/share/apps/korganizer/std.ics</filename>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>GroupDav Server (e.g. Open Groupware)</guilabel></term> +<listitem><para> +If you have access to a server that supports the +<ulink url="http://www.groupdav.org">GroupDav protocol</ulink>, add this +resource in order to be able to to save (and load) events<!--, journals, free/busy information?--> and to-dos +to the server. To add the resource, you will need to know the server &URL;, your +user name and your password. The GroupDav protocol supports the storage of +contacts, so you may want to add and configure the &kaddressbook; +resource too.</para> +<para>As of June 2005, the groupware servers that implement this protocol +are the <ulink url="http://www.opengropware.org">OpenGroupware server</ulink> +and the <ulink url="http://www.citadel.org">Citadel server</ulink>. An up to +date list can be obtained at the +<ulink url="http://www.groupdav.org">GroupDav website</ulink>. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Novell Groupwise Server</guilabel></term> +<listitem><para> +If you have access to a +<ulink url="http://www.novell.com/products/groupwise">Novell GroupWise Server</ulink> +(version 6.5 or later), add this resource in order to be able to to save (and load) +events, free/busy information <!--,journals ?-->and to-dos to the server. To add the resource, you will +need to know the server &URL;, your user name and your password. There is +support for storage of contacts, so you may want to configure &kaddressbook; +resource.</para> +<para>The most practical way to configure the access to a GroupWise server is +to use the <application>groupwisewizard</application> wizard. You can start it +from the command line prompt: + +<screen><prompt>$</prompt><command>groupwisewizard</command></screen> + +The wizard will configure not only &korganizer; to use the +GroupWise resources, but &kmail;, &kaddressbook; too.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Calendar on IMAP Server via &kmail;</guilabel></term> +<listitem><para> +If you have access to a server that shares calendar data via IMAP, add this +resource in order to be able to to save (and load) events, to-dos, free/busy +information and journal entries to the IMAP server. To enable IMAP access, you +will need to configure &kmail; first, then add the &korganizer; resource. +Also, since you are using &kmail; to contact the server, &korganizer; will +open &kmail; automatically, and use it to access your data. The +<quote>IMAP server via &kmail;</quote> schema supports the storage +of contacts, so you may want to add the &kaddressbook; resource too.</para> + +<para>Most IMAP servers can be used to hold calendar and address book resources, +allowing you to use access your data from just anywhere! If you are a user +looking for a simple way to access and manage your groupware information, +this is a simple and very efficient solution.</para> + +<para>To use this resource, it is necessary to configure &kmail; first. Choose +the <menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Configure &kmail;...</guimenuitem></menuchoice> menu item. +Click the <guilabel>Accounts</guilabel> icon in the configure dialog sidebar +and add the IMAP server as a disconnected IMAP incoming account. Now click the +<guilabel>Misc</guilabel> icon in the sidebar and click the +<guilabel>Groupware tab</guilabel> to enable and configure the IMAP resource +folder options. Only then you can add the &korganizer; (and &kaddressbook;) +resources. For more information on configuring &kmail;, consult the &kmail; +handbook.</para> + +<para>A more complete implementation of this schema is the +<ulink url="http://www.kolab.org">Kolab Server</ulink>. This groupware +implementation offers additional features for system administrators, such as +support of mixed client environments (&Microsoft; Outlook®, &kde; +<acronym>PIM</acronym> and web mail), a web administration interface, shared +address book, email server, &etc; As of June 2005, the groupware servers that +implement the <quote>Kolab 1</quote> and <quote>Kolab 2</quote> protocols are +the Kolab server, version 1 and 2, and the +<ulink url="http://www.citadel.org">Citadel server</ulink> (Kolab 1 only). An up +to date list can be obtained at the <ulink url="http://www.kolab.org">Kolab +website</ulink>.</para> + +<para>The most practical way to configure the access to a Kolab server is to use +the <application>kolabwizard</application> wizard application. You can start it +from the command line prompt: + +<screen><prompt>$</prompt><command>kolabwizard</command></screen> + +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Calendar in Local Directory</guilabel></term> +<listitem><para>Add this resource to be able to save and load your events, +to-dos and journal entries from a local folder. Each calendar item will be saved +in a separate file, inside the folder. +</para> +<para>Since there is only one file per event, to-do, or journal entry, &korganizer; +does not need to parse one big calendar file, sometimes with thousands of items +when saving or loading, just one single calendar item. Also, in case of file +corruption, you will lose only one calendar item, not the whole calendar.</para> +</listitem> +</varlistentry> + +<!-- +<varlistentry> +<term><guilabel>Calendar on Exchange Server (Experimental)</guilabel></term> +<listitem><para> +If you have access to a +<ulink url="http://www.microsoft.com/exchange">Exchange 2000 Server</ulink>, +add this resource in order to be able to to save (and load) +events FIXME:,journals, free/busy information and to-dos? to the server. To add the resource, you will +need to know the server &URL;, FIXME:port? your user name and your password. There +is support for (read only) contacts, so you may want to configure &kaddressbook; +resource.</para> +FIXME: does the wizard work? +<para>The most practical way to configure the access to a Exchange server is +to use the <application>exchangewizard</application> wizard. You can start it +from the command line prompt: + +<screen><prompt>$</prompt><command>exchangewizard</command></screen> + +The wizard will configure not only &korganizer; to use the +Exchange resources, but &kmail;, &kaddressbook; too.</para> +</listitem> +</varlistentry> +--> + +<varlistentry> +<term><guilabel>Calendar in Remote File</guilabel></term> +<listitem><para>Add this resource to be able to save and load your events, +to-dos and journal entries from a remote file. +<!--FIXME: make sure this is all true--> +There are two main advantages of keeping your calendar data in a remote server: +you can access your data even if you are away from your computer, and +you can let other people (for instance, a secretary) view it. +&korganizer; keeps a cache of the data locally. +</para> + +<screenshot id="screenshot-remotefile-resource"> +<screeninfo>A screenshot of &korganizer;'s Remote File Resource Configuration</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="remotefile-resource.png" format="PNG"/></imageobject> +<textobject><phrase>A screenshot of &korganizer;'s Remote File Resource Configuration</phrase></textobject> +<caption><para>A screenshot of &korganizer;'s Remote File Resource Configuration</para></caption> +</mediaobject> +</screenshot> + +<para>You can configure the resource to be read only, keeping the remote file +untouched. In this case, you won't need to supply a <quote><guilabel>Upload +to</guilabel></quote> location, just a <quote><guilabel>Download +from</guilabel></quote> location for the remote file. If you plan to use a +writable remote resource, you will have to supply both locations. The reason +to have separate locations, is that some servers may have an upload queue, +a place where you need to put the upload file, different from where it will be. +In most cases, if you have write access to the remote file, the <guilabel>Upload +to</guilabel> and <guilabel>Download from</guilabel> file locations should be +the same. +</para> + +<para>It is important to understand that the remote file resource does not +add or remove individual items from the remote file, it simply saves the +remote file over local cache when downloading and save the local cache over the +remote file when uploading. Therefore, if the resource is read only, it makes +sense to set the <guilabel>Automatic Reload</guilabel> option to a +<guilabel>Regular interval</guilabel>, but if not (if the resource is writable), +it is recommended to reload the file only before starting to edit it, by setting +the <guilabel>Automatic Reload</guilabel> option to <guilabel>On +startup</guilabel>, and to save it before exiting, by setting the +<guilabel>Automatic Save</guilabel> option at least to +<guilabel>On exit</guilabel>, or better yet, if you have a fast and stable +connection to the remote file, set it to <guilabel>On every change</guilabel> +to avoid data loss.</para> + +<warning><para>If you add, change or remove events, journal entries or to-dos and +reload the remote file, all your local changes will be lost, and the +file will revert to its previous state. This can happen in different scenarios +(for instance if the system crashes, &korganizer; will reload the remote file on +the next start, if you set the <guilabel>Automatic Save</guilabel> to +<guilabel>Never</guilabel>, or if you set the <guilabel>Automatic Reload</guilabel> +to a regular interval). If you plan to use a calendar resource in +writable mode, make sure that your connection is stable, configure the +resource to save the file on each change (or at frequent intervals), +and don't reload the file at regular intervals.</para> + +<para>A related, but opposite problem, is that two users cannot safely edit +the same remote file at the same time, because the remote file resource does not +offer a conflict resolution mechanism. For instance, if someone else changes +(and saves) the remote file, after you loaded it, and a some time later you save +the file, his changes will be lost. +</para></warning> + +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>SUSE &Linux; OpenExchange Server</guilabel></term> +<listitem><para> +If you have access to a +<ulink url="http://www.novell.com/products/groupwise">SUSE &Linux; OpenExchange +Server</ulink>, version 4.1, add this resource in order to be able to to save +(and load) events, free/busy information <!--,journals ?-->and to-dos to the server. To add the +resource, you will need to know the server &URL;, your user name and your +password. There is support for storage of contacts, so you may want to configure +&kaddressbook; resource.</para> +<para>The most practical way to configure the access to a GroupWise server is +to use the <application>sloxwizard</application> wizard. You can start it +from the command line prompt: + +<screen><prompt>$</prompt><command>sloxwizard</command></screen> + +The wizard will configure not only &korganizer; to use the +OpenExchange resources, but &kmail;, &kaddressbook; too.</para> +</listitem> +</varlistentry> + +<varlistentry> + +<!--FIXME: are there other XML-RPC servers?--> +<term><guilabel>eGroupware Server (via &XML;-RPC)</guilabel></term> +<listitem><para> +If you have access to a +<ulink url="http://www.egroupware.org">eGroupware +Server</ulink>, version 1.0, add this resource in order to be able to to save +(and load) events, free/busy information <!--,journals ?-->and to-dos to the server. To add the +resource, you will need to know the server &URL;, your user name and your +password. There is support for storage of contacts, so you may want to configure +&kaddressbook; resource.</para> +<para>The most practical way to configure the access to a eGroupware server is +to use the <application>egroupwarewizard</application> wizard. You can start it +from the command line prompt: + +<screen><prompt>$</prompt><command>egroupwarewizard</command></screen> + +The wizard will configure not only &korganizer; to use the +eGroupware resources, but &kmail;, &kaddressbook; too.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="managing-import-export"> +<title>Importing, Exporting and Maintaining Calendars</title> + +<para>While local files are just one among many other resources that can be used +by &korganizer;, they are the most convenient way to share calendars, save +copies, or import items from your old calendar program.</para> + +<sect2 id="managing-import"> +<title>Importing Calendars</title> + +<para>If you have a iCalendar or vCalendar file, and you +would like to import it, choose the <menuchoice><guimenu>File</guimenu> +<guisubmenu>Import</guisubmenu><guimenuitem>Import Calendar...</guimenuitem> +</menuchoice>. &korganizer; will ask you if you want to <guilabel>Add as new +calendar</guilabel>, which adds the calendar file as a new local file resource, +<guilabel>Merge into existing calendar</guilabel>, which merges the calendar +items into an existing resource or <guilabel>Open in separate window</guilabel>, +which will allow you to view and edit the calendar, but will not add to +its default view.</para> + +<para>A good time to do this would be if you received a +vCalendar with a few entries via email, for instance, or if you are planning +to import your calendar from another application. In the latter case, the first +thing to do is to use that application to export the calendar data in one of the +formats above, or use a tool to convert from the application's native format. If you +are migrating from &Microsoft; Outlook®, please check +<xref linkend="outlook-to-vcalendar-ws" />.</para> + +<para>If you have used <application>ical</application>, a popular but +older calendar program for &UNIX;, you may wish to <action>import your events, +journal entries, and to-dos</action> directly to &korganizer;. To do so, choose the +<menuchoice><guimenu>File</guimenu><guisubmenu>Import</guisubmenu> +<guimenuitem>Import From &UNIX; Ical Tool</guimenuitem></menuchoice>. +This action will read the <filename>.calendar</filename> file from your home +folder and merge any entries it contains into your current calendar. +If any errors or suspicious things occur during the process, you will be +notified via a message box.</para> + +</sect2> + +<sect2 id="managing-export"> +<title>Exporting Calendars</title> + +<para>You can export your data as a web page, or as an iCalendar or +vCalendar file, which are supported by most scheduling applications. +The web page can be used to publish your calendar and to-dos list on the +web or on the local network. Either way, &korganizer; will export all calendar +items from the enabled (checked) resources which are +<link linkend="filters-view">not filtered out</link> (let's call these items +<quote>active</quote> items). In other words, if you cannot see a calendar +item, it won't be in the exported file. To filter out the undesired items +before exporting them, you can create +<link linkend="filters-view">filters</link>. Filters even are more effective +if you classify your events and to-dos in +<link linkend="categories-view">categories</link>. To enable and disable +resources, check or uncheck the resource box in the +<link linkend="managing-resources"><guilabel>Resource View</guilabel></link> +sidebar.</para> + +<para>To export all your <quote>active</quote> events, to-dos and journal entries +(independent of to what resource they belong) as a new iCalendar +file, choose the <menuchoice><guimenu>File</guimenu><guisubmenu>Export</guisubmenu> +<guimenuitem>iCalendar...</guimenuitem></menuchoice> menu item. To export the same +data as a new vCalendar file choose the <menuchoice><guimenu>File</guimenu> +<guisubmenu>Export</guisubmenu> <guimenuitem>vCalendar...</guimenuitem> +</menuchoice> menu item. The <guilabel>Save As</guilabel> dialog will pop up. +Enter the file name and location for the new file to complete the export +action.</para> + +<para>You can export your calendar or a part of it as a &HTML; +file, suitable for publishing in the web. Anyone with access to this file, +using a web browser, will be able to view it. This is an easy way to share +calendar information with your colleagues and friends.</para> + +<!--TODO: use case: export your friends birthdays?--> + +<procedure id="procedure-export-html"> +<step><para>Disable all the resources you don't want to export, and filter out +the items you don't want to export.</para></step> +<step><para>Choose the <menuchoice><guimenu>File</guimenu> +<guisubmenu>Export</guisubmenu><guimenuitem>Export Web Page...</guimenuitem> +</menuchoice> menu item. You will get a window with three tabs: +<guilabel>General</guilabel>, <guilabel>Events</guilabel>, and +<guilabel>To-dos</guilabel>.</para></step> +<step><para><guilabel>General</guilabel> tab:</para> +<substeps> +<step><para>Specify the date range that you want published. Enter dates +manually or use the Calendar Widget.</para></step> +<step><para>If you want to export to-dos, check the <guilabel>Export +to-do list</guilabel> box.</para></step> +<step><para>If you want to export the items displayed in the month view, check the +<guilabel>Export in month view</guilabel> box.</para></step> +<step><para>If you want to export events formatted as a list of events, check the +<guilabel>Export events as list</guilabel> box.</para></step> +<step><para>Specify the web output file in the <guilabel>Output file</guilabel> +field. If set another location, press the <guibutton><inlinemediaobject> +<imageobject><imagedata fileref="i_file_open.png" format="PNG"/></imageobject> +</inlinemediaobject>Browse Folders</guibutton> button to find it.</para></step> +</substeps></step> +<step><para><guilabel>Events</guilabel> tab: specify if you want to include +categories and attendees in the exported web page.</para></step> +<step><para><guilabel>To-dos</guilabel> tab: specify if you want to list Due +Dates, Categories, and Attendees.</para></step> +</procedure> + +</sect2> + +<sect2 id="managing-purge-archive"> +<title>Maintaining Your Calendars</title> + + +<para>Contemporary computers have ample storage space. However, if you + synchronize your &korganizer; calendar with a limited-memory machine like the + Palm device, you will find archiving useful. The performance of &korganizer; + can also become worse when there are many events. To archive old +items, follow the procedure below:</para> + +<procedure> +<step><para>Choose the <menuchoice><guimenu>File</guimenu><guimenuitem>Archive +Old Entries...</guimenuitem></menuchoice>.</para></step> +<step><para>Fill in the date in <guilabel>Archive now items older than</guilabel> field or +use the Calendar Widget to choose the date. Alternatively, you can automatically +archive all items older than a certain period of time.</para></step> +<step><para>If you have chosen archiving, you must also provide a filename for +the archive in the <guilabel>Archive File</guilabel> field. If you want to +re-use an older archive file, press the <guilabel>Browse</guilabel> button +and find an existing archive. The entries will be added to the file, +so any item already in the file will not be modified.</para></step> +</procedure> + +<para>Archiving will keep all old items in a file, including completed +to-dos. But if you do not want to keep completed to-dos at all, choose the +<menuchoice><guimenu>File</guimenu><guimenuitem>Purge Completed To-dos</guimenuitem> +</menuchoice> menu item to remove all the completed to-dos from your +active resources. If you want to keep your completed to-dos, but +do not wish to view in the to-do lists, consider +<link linkend="filters-view">filtering them out</link> instead of purging them. +</para> + +</sect2> + +</sect1> + +<sect1 id="managing-get-hot-new-stuff"> +<title>Uploading and Downloading Using Get Hot New Stuff</title> + +<para>If you have a calendar containing events of public interest, such as +a conference or championship schedule, you can upload it (or check if there +is something worth downloading) using the +<ulink url="http://ghns.berlios.de/">get hot new stuff framework</ulink>. +</para> + +<para> +To open the <guilabel>Get Hot New Stuff</guilabel> +dialog, which offers a list of calendars to download, choose the +<menuchoice><guimenu>File</guimenu><guisubmenu>Import</guisubmenu> +<guimenuitem>Get Hot New Stuff...</guimenuitem></menuchoice> menu item. +If you select one of the calendars, a dialog with the list of events from the +calendars will appear. To merge the displayed events with your default resource, +press <guilabel>Merge</guilabel>.</para> + +<para> +To open the <guilabel>Upload Hot New Stuff</guilabel> dialog, which allow you +to export calendars containing events which may be useful to other people, such +as a conference program, a list of holidays, special events, &etc;, +choose the <menuchoice><guimenu>File</guimenu><guisubmenu>Export</guisubmenu> +<guimenuitem>Upload Hot New Stuff...</guimenuitem></menuchoice>.</para> + +<para>Before uploading the events, make sure you have +<link linkend="filters-view">filtered out</link> all unrelated data.</para> + +</sect1> + +</chapter> + +<chapter id="chapter-views-and-filters"> +<title>Views and Filters</title> + +<para>While calendars (resources) can hold events, to-dos and / or journal +entries, these items are very different in nature. To-dos may have no +date associated with them, so a schedule view is not suitable to them. +Journal entries are a collection your reflections, occurrences or experiences. +They require their own view mode, as they are not related +with the list upcoming events or the list of to-dos, &etc;</para> + +<para>To solve the challenge of displaying your information in an useful and +intuitive fashion, &korganizer; offers different views, filters and search +capabilities. You can also assign related events and to-dos to +categories, which will help you to view them later, using filters or +colors.</para> + +<sect1 id="description-view"> +<title>&korganizer; Views</title> + +<para>In this section, we describe the different view modes, and present an +overview of how to browse your personal data using &korganizer;.</para> + +<para>The &korganizer; window can be divided in two main areas: the +main window and the sidebar. The main window displays the main views and the +sidebar displays the date navigator, the +to-do view, the item viewer and the resource view. To show or hide the +sidebar components, check or uncheck the menu items under the +<menuchoice><guimenu>Settings</guimenu> +<guisubmenu>Sidebar</guisubmenu></menuchoice> submenu.</para> + +<para>The date navigator is provided to browse and select dates. Today's date +will be outlined with a small box, dates which have events scheduled on them +will be bold (daily or weekly recurring events may not be marked as bold, +<link linkend="config-main-views">depending on the view configuration</link>), +and holidays will be colored red. If you want to jump to a date, simply click +on it. Hold down the mouse to select multiple contiguous dates at once. +The <guilabel>What's Next</guilabel>, +<guilabel>List</guilabel>, <guilabel>Agenda</guilabel> and +<guilabel>Journal</guilabel> views will only show events, to-dos or +journals items from the dates selected in the date navigator. The +<guilabel>Month</guilabel> view will show events or to-dos from the first +month shown in the date navigator (the selected days in the month won't change +the month view, only month changes).</para> + +<para>The to-do view sidebar component lists your to-dos, just like the +<link linkend="todo-view">To-do view</link>. It is useful if you want +to see your to-dos while using the other views.</para> + +<para>The item viewer sidebar component shows details of the currently selected +events, to-dos or journal entries.</para> + +<para>Finally, the resource viewer sidebar component allow you to enable or +disable the resources on the list, by checking or unchecking the resource +box, and to manage your resources. For more information, please check +<xref linkend="managing-resources" />.</para> + +<para>You can also browse your calendar view choosing +the <menuchoice><guimenu>Go</guimenu> +<guimenuitem>Go Backward</guimenuitem></menuchoice> menu item (or pressing the +<inlinemediaobject><imageobject><imagedata fileref="i_go_backward.png" +format="PNG"/></imageobject></inlinemediaobject>toolbar button), which goes to +the previous day, week, month or year, choosing the <menuchoice><guimenu> +Go</guimenu><guimenuitem>Go Forward</guimenuitem></menuchoice> menu item (or +pressing the <inlinemediaobject><imageobject> +<imagedata fileref="i_go_forward.png" format="PNG"/></imageobject> +</inlinemediaobject>toolbar button), which goes to +the next day, week, month or year (depending on the view), and choosing the +<menuchoice><guimenu>Go</guimenu><guimenuitem>Go to Today</guimenuitem> +</menuchoice> menu item (or pressing the <inlinemediaobject><imageobject> +<imagedata fileref="i_go_to_today.png" format="PNG"/></imageobject> +</inlinemediaobject>toolbar button), which will include the current day in the +current view.</para> + +<sect2 id="whatsnext-view"> +<title>What's Next View</title> + +<para>This view displays events and to-dos in a simple format you can +quickly read. All open to-dos will be displayed, but only the events from +the days selected in the <guilabel>Date Navigator</guilabel> sidebar will be +shown. Events and to-dos are displayed one per line.</para> + +<para>Switch to the What's Next view by choosing the +<menuchoice><guimenu>View</guimenu> +<guimenuitem>What's Next</guimenuitem></menuchoice> +menu item or pressing the <guilabel><inlinemediaobject><imageobject><imagedata fileref="i_view_whatsnext.png" + format="PNG"/></imageobject></inlinemediaobject>What's Next</guilabel> button +in the toolbar.</para> + +</sect2> + +<sect2 id="list-view"> +<title>List View</title> + +<para>This view displays all your to-dos, events and journal entries for +the dates selected in the date navigator as a list. Open to-dos that are +not due on the selected dates are not shown. This view is good for displaying +many different items in a compact fashion. It is also useful if your +events are spread out over a long time period that would not be displayed +completely on the screen when using one of the other views.</para> + +<para>The items are displayed one per line. Columns show if an alarm is set +(a bell icon displayed in it means the alarm is set), if it repeats multiple +times (a chasing-arrows icon means a repeating event), the start and end time +information. Hovering the mouse over an item will bring up a +tooltip with detailed information about the item.</para> + +<para>Switch the display to the list view by choosing the +<menuchoice><guimenu>View</guimenu> +<guimenuitem>List</guimenuitem></menuchoice> +menu item or pressing the <guilabel><inlinemediaobject><imageobject><imagedata fileref="i_view_list.png" + format="PNG"/></imageobject></inlinemediaobject>List</guilabel> button +in the toolbar.</para> + + +</sect2> + +<sect2 id="agenda-view"> +<title>Agenda View</title> + +<!--TODO: add agenda view options, color of resources and categories--> + +<para>The agenda view presents your events or due to-dos for one or more days, +sorted chronologically. You can also see the length of each event in the day +timetable. The <guilabel>Day</guilabel>, <guilabel>Work Week</guilabel> and +<guilabel>Week</guilabel> views are variations of the agenda view. +In fact, you can set the days shown in the agenda view at any time by selecting +them in the date navigator.</para> + +<para>Time is indicated by a time bar on the left side of the view. A scrollbar +on the right is provided when the whole day cannot be displayed on a single +screen (which is the usual case). Each rectangle in the view represents an +individual event or to-do due for that time, and displays the start and end time +and summary. A <guiicon>bell</guiicon> icon is displayed if an alarm is set, and +a <guiicon>chasing-arrows</guiicon> icon is displayed if it repeats multiple +times. Hovering the mouse over an calendar item will bring up a tooltip +with the item detailed information. To make &korganizer; show a red line +marking the current-time on the current day (the Marcus Bains line), +check the <guilabel>Show current-time (Marcus Bains Line)</guilabel> box in the +<link linkend="config-main-views">&korganizer; view +configuration</link>.</para> + +<para>Any event can be re-sized with your mouse. Simply move the mouse pointer +near the top or bottom edge of the event, and drag the edge up or +down. This way you can visually modify the starting and ending time of your +event. This also works in the Week and Work Week views. In other words, it +is possible to change start and end times with the mouse by just moving the +upper or lower border of the event to the new time.</para> + +<para>Any event can be rescheduled with your mouse. Move the mouse pointer over +the event, and drag it to a new time location. This also works in the Week and +Work Week views. Events can be moved to other, presently non-visible dates. +Move the mouse pointer over the event, and drag it to the date navigator.</para> + +<para>Since the agenda view cannot contain the whole day on most screens, you +will have to scroll up and down to see the whole day. There is a useful hint that +tells you if there are any currently invisible events above or below your current +view; it is a small down-pointing at the bottom of each day view or +up-pointing arrow at the top.</para> + +<tip><para>There are a useful shortcut for adding events: + +<itemizedlist> +<listitem><para>Double-click any +open region of time, and &korganizer; will automatically create an event with +default duration (which is customizable in the preferences dialog). +You can immediately add the title. The events <quote>snap</quote> to +half-hour increments, rounding off to the closest half hour from where you +clicked.</para></listitem> +<listitem><para>Select any open region of time, and double click it or start +writing the title of the event. &korganizer; will automatically set the +duration and start time as defined by the selection area in the agenda +view.</para></listitem> +</itemizedlist> +</para></tip> + +<para>To help you organize your agenda, the color of the events reflect their +category, and depending on the <link linkend="config-main-views">&korganizer; +view configuration</link>, it may also reflect its +<link linkend="managing-resources">resource</link>. Therefore, if you assign +<link linkend="categories-view">categories to events</link> and +<link linkend="config-main-colors">different colors to categories</link> , you +will be able to quickly identify the type of event by its color. +</para> + +<para> +The aganda view can display events from all your calendars merged into one view or +show a view per calendar. Having both views available via tabs is also possible and +can be <link linkend="config-main-views">customized in the preferences dialog</link>. +</para> + +<sect3 id="day-view"> +<title>Day View</title> + +<para>This view presents the <link linkend="agenda-view">agenda view</link> for +a single day.</para> + +<para>Switch the display to the day view by choosing the +<menuchoice><guimenu>View</guimenu> +<guimenuitem>Day</guimenuitem></menuchoice> +menu item or pressing the <guilabel><inlinemediaobject><imageobject><imagedata fileref="i_view_day.png" + format="PNG"/></imageobject></inlinemediaobject>Day</guilabel> button +in the toolbar.</para> + +</sect3> + +<sect3 id="next-x-days-view"> +<title>Next X Days View</title> + +<para>This view presents the <link linkend="agenda-view">agenda view</link> for +the next days, starting from today. You can change the number of days to be +displayed in the <link linkend="config-main-views">&korganizer; view +configuration</link>. The default value is 3.</para> + +<para>Switch the display to the next days view by choosing the +<menuchoice><guimenu>View</guimenu> +<guimenuitem>Next X Days</guimenuitem></menuchoice> +menu item, (X represents the number of days, usually 3).</para> + +</sect3> + + +<sect3 id="week-view"> +<title>Week View</title> + +<para>The week view provides a view similar to the day view. Events for seven +days are shown next to each other.</para> + +<para>Switch the display to the week view by choosing the +<menuchoice><guimenu>View</guimenu> +<guimenuitem>Week</guimenuitem></menuchoice> +menu item or pressing the <guilabel><inlinemediaobject><imageobject><imagedata fileref="i_view_week.png" + format="PNG"/></imageobject></inlinemediaobject>Week</guilabel> button +in the toolbar.</para> + +</sect3> + +<sect3 id="workweek-view"> +<title>Work Week View</title> + +<para>This is the same as the week view, except that it shows only the working +days of the week.</para> + +<para>Switch the display to the work week view by choosing the +<menuchoice><guimenu>View</guimenu> +<guimenuitem>Work Week</guimenuitem></menuchoice> +menu item or pressing the <guilabel><inlinemediaobject><imageobject><imagedata fileref="i_view_work_week.png" + format="PNG"/></imageobject></inlinemediaobject>Work Week</guilabel> button +in the toolbar.</para> + +</sect3> + +</sect2> + + +<sect2 id="month-view"> +<title>Month View</title> + +<!--TODO: add month view options--> + +<para>The month view shows all the events and due to-dos for the current +month in a familiar month calendar layout. Each cell in the view +represents a day, and each day contains all of the events that can fit in the +area provided (maximizing the window will enable you to see more appointments). +Information on repeating and alarm status is indicated through +<guiicon>bell</guiicon> and <guiicon>chasing arrows</guiicon> icons, just like +in other views.</para> + +<para>Navigate the month view using the date navigator arrows, +or the items and toolbar buttons from the <guilabel>Go</guilabel> menu. +Since the visible area of a day cell may not contain all events and +to-dos, you can use the keyboard to browse the items, or, if you check +the <guilabel>Enable scrollbars in month view cells</guilabel> box in the +<link linkend="config-main-views">&korganizer; view configuration</link>, you +can use them to see all the events and to-dos from that day.</para> + +<para>Hover your mouse over any calendar item to display a tooltip with the +item details. Double click an empty area to create an event, double +click any calendar item to edit it.</para> + +<para>To help you organize your data, the color of the events may +reflect their category, and its <link linkend="managing-resources">resource</link>, +depending on the <link linkend="config-main-views">&korganizer; +view configuration</link>. Therefore, if you assign +<link linkend="categories-view">categories to events</link> and +<link linkend="config-main-colors">different colors to categories</link>, +you can identify the type of event (or resource) by its color. +</para> + +<para>Switch the display to the month view by choosing the +<menuchoice><guimenu>View</guimenu> +<guimenuitem>Month</guimenuitem></menuchoice> +menu item or pressing the <guilabel><inlinemediaobject><imageobject><imagedata fileref="i_view_month.png" + format="PNG"/></imageobject></inlinemediaobject>Month</guilabel> button +in the toolbar.</para> + +</sect2> + +<sect2 id="timeline-view"> +<title>Timeline View</title> + +<para> The timeline view shows all events for the selected timespan in a gantt +view. Every calendar is displayed in a separate line. </para> + +<para>Hover your mouse over any calendar item to display a tooltip with the +item details. Double click an empty area to create an event, double +click any calendar item to edit it.</para> + +</sect2> + +<sect2 id="todo-view"> +<title>To-do List</title> + +<para>The to-do list provides a place for you to jot down quick (or long-term) +notes about things that need to be done. The to-do view sidebar +component appears right below the Date Navigator. You can also display it in the +main panel if you click the <guilabel><inlinemediaobject><imageobject> +<imagedata fileref="i_view_todo_list.png" format="PNG"/></imageobject> +</inlinemediaobject>To-do List View</guilabel> toolbar button or if you choose the +<menuchoice><guimenu>View</guimenu><guimenuitem>To-do +List</guimenuitem></menuchoice> menu item.</para> + +<para>You can give your to-do a <quote>date due</quote>, in other words a +date when the to-do should be finished.</para> + +<para>You can also assign priorities to to-dos, and they will appear +sorted in order of priority. The lower the number, the higher the priority, +except that zero (0) is defined as <quote>no priority.</quote></para> + +<para>To make a new to-do entry, right click the to-do view sidebar component, +or the to-do list view, and choose the <guimenuitem>New To-do</guimenuitem> menu +item. If you right click an already existing to-do, you will get more +choices: you can <guimenuitem>Show</guimenuitem> the summary, +<guimenuitem>Edit...</guimenuitem> the to-do details, +<guimenuitem>Delete</guimenuitem> the to-do altogether, or you can +create a <guimenuitem>New Sub-To-do...</guimenuitem> You could for example make +a large to-do like building a house, and make sub-to-dos like choosing the +right building site, hiring an architect, hiring workers and finally arranging +a party for your friends.</para> + +<para>When you choose <guimenuitem>New To-do...</guimenuitem>, a dialog will +pop up, allowing you to enter all necessary <link +linkend="entering-data-to-do">information</link>.</para> + +<para>Click any to-do in the list to highlight it. If you click the +thick-line box on the left of the to-do description, you will change the +<quote>completed</quote> status of the to-do. If you double-click the to-do +description, you will be able to edit all its details.</para> + +<para>You may also pick <link linkend="managing-purge-archive">Purge +Completed</link> from the <mousebutton>right</mousebutton> mouse button menu to +delete all to-do entries that you have marked completed.</para> + +<para>To-dos can also dragged around with the mouse to rearrange the +hierarchy or to exchange to-dos with other calendar windows. You can also +read an <link linkend="other-features-drag-and-drop">overview</link> of all +available drag-and-drop operations.</para> +</sect2> + +<sect2 id="journal-view"> +<title>Journal View</title> + +<para>The journal view provides a place for you to record your reflections, +occurrences or experiences. You can display the journal view in the main +panel if you press the <guilabel><inlinemediaobject><imageobject> +<imagedata fileref="i_view_journal.png" format="PNG"/></imageobject> +</inlinemediaobject>Journal View</guilabel> toolbar button or if you choose the +<menuchoice><guimenu>View</guimenu><guimenuitem>Journal</guimenuitem> +</menuchoice> menu item.</para> + +<para>When you click the <guilabel>add journal entry</guilabel> link, a new journal +entry will be created. If you want to edit an journal entry, just click the +text box and edit it! To remove a journal entry, press the <inlinemediaobject> +<imageobject><imagedata fileref="i_edit_delete.png" format="PNG"/> +</imageobject></inlinemediaobject>delete button next to the +<guilabel>Title</guilabel> of the journal entry.</para> + +</sect2> + +</sect1> + +<sect1 id="categories-view"> +<title>Categories</title> + +<!--TODO: Add screenshot?--> + +<para>To help you organize your entries in related groups, you can assign +categories to events and to-dos. If you assign categories, you can use them +later when searching, filtering, and displaying events and to-dos.</para> + +<para>To assign categories when editing or creating new +<link linkend="entering-data-events-general">events</link> or +<link linkend="entering-data-to-do-general">to-dos</link>, press the +<guilabel>Select Categories...</guilabel> button in the +<guilabel>General</guilabel> tab to open the +<guilabel>Select Categories</guilabel> dialog. You can assign more than +one category for each item.</para> + +<para>To create, delete and edit categories, choose the <menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Manage Categories...</guimenuitem> +</menuchoice> menu item to open the <guilabel>Edit Categories</guilabel> dialog. +If you assign <link linkend="config-main-colors">different colors to categories</link>, +you will be able to quickly identify the type of event by its color, either in +the agenda view or in the month view (depending on the +<link linkend="config-main-views">&korganizer; view configuration</link>). +</para> + +</sect1> + +<sect1 id="filters-view"> +<title>Filters</title> + +<para>To help you view, find and export your data, you can create and +use filters for your calendars. For instance, if you don't want to view +completed to-dos, you can filter them out, instead of +<link linkend="managing-purge-archive">purging them</link>. If you assign +categories, you can use them to create filters.</para> + +<para>To create, delete and edit filters, choose the <menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Manage View Filters...</guimenuitem> +</menuchoice> menu item to open the <guilabel>Edit Calendar Filters</guilabel> +dialog. Using this dialog, you can create, delete +and edit filters that will affect which items will be displayed by +&korganizer;.</para> + +<!--TODO: Add detailed description of the dialog. Is it stable yet?--> + +<para>The <menuchoice><guimenu>View</guimenu> +<guisubmenu>Filter</guisubmenu></menuchoice> submenu and the filter toolbar drop +down offer access to all available filters created using +the <link linkend="menu-settings-edit-filters"><guilabel>Edit +Filters</guilabel></link> dialog. To toggle the display of the filters toolbar +on and off, choose the <menuchoice><guimenu>Settings</guimenu> +<guisubmenu>Toolbars</guisubmenu><guimenuitem>Filter toolbar</guimenuitem></menuchoice>. +If you don't want to use any filter, choose <guilabel>No filter</guilabel>.</para> + +<para>Filters are useful when <link linkend="managing-export">exporting your +calendar</link>. If you use a filter, only the filtered (visible) items will +be exported. Also, filters are more effective when the items are already +classified and organized in <link linkend="categories-view">categories</link>, +as you can easily create filters based on categories.</para> + +</sect1> + +<sect1 id="search-view"> +<title>Searching</title> + +<para>Choose the <menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Find</guimenuitem></menuchoice> menu item, press the +<guiicon><inlinemediaobject><imageobject><imagedata fileref="i_edit_find.png" + format="PNG"/></imageobject></inlinemediaobject>Find</guiicon> button in the +toolbar, or press the <keycombo action="simul">&Ctrl;<keycap>f</keycap> +</keycombo> shortcut to find items (events, to-dos or journal +entries) according to title, description, and/or categories. +The find action will only search the specified fields.</para> + +<tip><para>You can use wildcards if you do not remember the exact summary. If +you don't know single character of the summary, put <userinput>?</userinput> +instead of the missing character. If you don't know more characters, use +<userinput>*</userinput>. For instance if you know that the event or to-do has +<emphasis>meeting</emphasis> in the beginning and <emphasis>product</emphasis> +after, you would write <userinput>meeting*product</userinput> in the Find dialog. +&korganizer; will locate entries like <quote>To-do: arrange meeting about the new product</quote>, +<quote>Meeting to discuss the old product line</quote> and +similar. Letter case is ignored.</para></tip> + +<para>The result of the Find operation is a list of events, journal entries +and/or to-dos with the specified keyword. The search list characteristics are +the same as the <link linkend="list-view">List View</link>.</para> + +<para>This resulting list is active. You can double-click a line to display +or edit the event or to-do details. Get more information about these details in +<xref linkend="entering-data-events" /> and +<xref linkend="entering-data-to-do" />.</para> + +</sect1> + +</chapter> + +<chapter id="entering-data"> +<title>Entering Data</title> + +<sect1 id="entering-data-events"> +<title>Events</title> + +<para>Events are future or past appointments, like business meetings, personal +anniversaries and cinema visits. An event can also take several days, like +holidays.</para> + +<para>Entering a new event is very easy. Just choose the +<menuchoice><guimenu>Actions</guimenu><guimenuitem>New +Event...</guimenuitem></menuchoice> menu item. A window with +<guilabel>General</guilabel>, <guilabel>Recurrence</guilabel>, +<guilabel>Attendees</guilabel>, <guilabel>Free/Busy</guilabel>, and +<guilabel>Attachments</guilabel> tabs will appear.</para> + +<para>If you wish you can use a different way to create a new event:</para> + +<procedure> +<step><para>Use the Date Navigator to go to the event date.</para></step> + +<step><para>Click the desired view's icon on the +<guimenu>View Toolbar</guimenu> or select the desired view from the +<guimenu>View</guimenu> menu. Since your event starts at a particular time, +you should choose a <link linkend="reference-menus-view">view</link> +that displays hours of the day. You may choose <guimenuitem>Day</guimenuitem>, +<guimenuitem>Work Week</guimenuitem> view or <guimenuitem>Week</guimenuitem> +view. The <guimenuitem>Month</guimenuitem> view is more suitable for +to-dos, described below.</para></step> + +<step><para>In the main panel, double click the time and date when your +event starts. </para></step> + +<step><para>A dialog with +<guilabel>General</guilabel>, <guilabel>Recurrence</guilabel>, +<guilabel>Attendees</guilabel>, <guilabel>Free/Busy</guilabel>, and +<guilabel>Attachments</guilabel> tabs appears. +Enter your data as described below.</para></step> +</procedure> + +<sect2 id="entering-data-events-general"> +<title><guilabel>General</guilabel> Tab</title> + +<para>This is a thorough description of the individual event window fields and +widgets. Not all fields have to be filled in; some can be left empty. Read the +<link linkend="entering-data-required-fields">Required fields section</link> +for detailed information. And if you prefer to learn by example, there's one +in the <link linkend="examples-entering-event">Entering event</link> section. +</para> + +<screenshot id="screenshot-event-general"> +<screeninfo>A screenshot of &korganizer;'s Edit Event dialog - General tab</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="event-general.png" format="PNG"/></imageobject> +<textobject><phrase>A screenshot of &korganizer;'s Edit Event dialog - General tab</phrase></textobject> +<caption><para>A screenshot of &korganizer;'s Edit Event dialog - General tab</para></caption> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Title:</guilabel></term> +<listitem><para>Enter short description of the event into the +<guilabel>Title</guilabel> field. This description is the text shown +on the &korganizer; main panel.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Location:</guilabel></term> +<listitem><para>Enter short description of the <guilabel>location</guilabel> +where the event will take place.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Date & Time</guilabel></term> +<listitem><para>The &korganizer; suggested Start and End dates of your event. + Events are +expected to start and end on the same date. Change these dates as desired. Enter +the dates directly or use the <link linkend="glossary" + endterm="gloss-calendar-widget"> +Calendar Widget</link>. Select the time from quarter hour intervals, or enter +the desired time directly into the time fields. These fields are only available +when the <guilabel>Time associated</guilabel> box is checked.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Time associated</guilabel></term> +<listitem><para>Uncheck the <guilabel>Time associated</guilabel> box if your +event is not scheduled on an exact time.</para> + +<tip><para>Most events are scheduled to an exact time. If your event does not +need specific time, perhaps it should be created as a <link +linkend="entering-data-to-do">to-do</link></para></tip></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Reminder</guilabel></term> +<listitem><para>Check the <guilabel>Reminder</guilabel> box if +&korganizer; should remind you about an event.</para> +<!-- +<tip><para>&korganizer; can also run a specific program at that time. +Make sure, however, that you have sufficient rights to run that +program; if you do not, the program will not run.</para></tip>--> +<para>Choose how many minutes, hours or days before the event you want to be +reminded, or click the <guibutton>Advanced</guibutton> button to open the +<guilabel>Edit Reminders</guilabel> dialog. Using this dialog, you can set +repeating intervals for your reminders, and create special reminders that play +sounds, run programs, or send emails.</para> + +<!--Click the musical <guiicon>Note</guiicon> symbol to choose the +alarm sound. Click the <guiicon>Gear</guiicon> icon to browse for a +program that should run at the alarm time.</para>--></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show Time As:</guilabel></term> +<listitem><para>The duration of the event may be shown as Busy or Free in your +schedule. Choose it from the <guilabel>Show Time As</guilabel> +menu.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Details:</term> +<listitem><para>Enter a long description of the event in the large, untitled +rectangle. You can write as many details as you wish here. For example, If the +event is, say, planned general repair of your car, you can list all items that +need repairing. Later on you can print this list and hand it over to the +serviceman. If the event is shopping, you should list the goods that you +need to buy. Print the event and take it to the shop with +you.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Select Categories</guilabel></term> +<listitem><para>You can assign several +<link linkend="categories-view">categories</link> to a calendar item. Click the +<guilabel>Select Categories</guilabel> button to open the +<guilabel>Select Categories</guilabel> dialog. Check the category boxes to +assign suitable categories to the event. You can also add a new category, modify +a category or delete a category by pressing the button +<guilabel>Edit Category</guilabel>.</para> + +<tip><para>Your language lesson at work may belong to both Business +and Education categories, while the anniversary of your marriage belongs to +either Personal or Special Occasion - it is your choice.</para></tip> +</listitem> +</varlistentry> + +<!--TODO: check if the following is still true--> +<varlistentry> +<term><guilabel>Access:</guilabel></term> +<listitem><para>Choose <guilabel>Private</guilabel> or <guilabel>Confidential</guilabel> +to keep the event private or confidential. Currently, this choice correctly +sets the <quote>CLASS</quote> attribute of the events to +<quote>PUBLIC</quote>, <quote>PRIVATE</quote> or <quote>CONFIDENTIAL</quote>. +However, if these settings are really used to restrict the access of the information +depends on the client and / or groupware server implementation.</para> +<warning><para>Currently, &korganizer; <emphasis>will</emphasis> display +items owned by other people and marked as confidential. Other +clients may treat them differently, but be careful when publishing private or +confidential events: vCalendar and iCalendar are text files, and can be read +with any text editor (if someone has read access to them). So if you want to +keep items really confidential, make sure you use a resource that +only you can access.</para></warning></listitem> +</varlistentry> + +</variablelist> + +<para>When you want to confirm, call off or revert the entered data, choose +among the <link linkend="reference-action-buttons">Action Buttons</link>, +<guibutton>OK</guibutton>, <guibutton>Apply</guibutton> and +<guibutton>Cancel</guibutton>.</para> + +</sect2> + +<sect2 id="entering-data-events-recurrence"> +<title><guilabel>Recurrence</guilabel> Tab</title> + +<para>Some events take place regularly. You can specify their exact scheduling +here.</para> + +<screenshot id="screenshot-event-recurrence"> +<screeninfo>A screenshot of &korganizer;'s Edit Event dialog - Recurrence tab</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="event-recurrence.png" format="PNG"/></imageobject> +<textobject><phrase>A screenshot of &korganizer;'s Edit Event dialog - Recurrence tab</phrase></textobject> +<caption><para>A screenshot of &korganizer;'s Edit Event dialog - Recurrence tab</para></caption> +</mediaobject> +</screenshot> + + +<note><para>To activate the settings, start by checking the +<guilabel>Enable recurrence</guilabel> check box. If it is not checked, you are +not able to make any changes on this tab.</para></note> + +<para>The Recurrence tab window is divided into four groups: +<guilabel>Appointment Time</guilabel>, <guilabel>Recurrence Rule</guilabel>, +<guilabel>Recurrence Range</guilabel>, and <guilabel>Exceptions</guilabel>. +</para> + +<sect3 id="recurrence-event-time"> +<title><guilabel>Appointment Time</guilabel></title> + +<para>The appointment time is set in the <link linkend="entering-data-events-general"> +<guilabel>General</guilabel> tab window</link>. It is displayed here to guide +you while you set the recurrence options.</para> + +</sect3> + +<sect3 id="recurrence-recurrence-rule"> +<title>Recurrence Rule</title> + +<para>Choose if you want to repeat this event daily, weekly, monthly or +yearly. More detailed options are as follows:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Daily</guilabel></term> +<listitem><para>Specify whether the event occurs every day (1), every other +day (2) and so on.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Weekly</guilabel></term> +<listitem><para>Specify whether the event occurs every week (1), every other +week (2) and so on. Also specify the days (Sunday ... Monday) on which the +event occurs. </para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Monthly</guilabel></term> +<listitem><para>You can either have the event occur on the same day of the +month, or in a specific week on a specific day of the week. You need to +choose between these two possibilities. By default, &korganizer; assumes you +want to repeat on the same calendar day of the month (for instance the 15th). +You can also adjust the period, so you can repeat monthly, tri-monthly and so +on.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Yearly</guilabel></term> +<listitem> +<para>This is similar to Monthly. You need to choose whether or not you +are indicating a calendar day of the year (⪚, the 250th day of the +year) - <guilabel>Recur on day <replaceable>#</replaceable> of the +year</guilabel>, in in a specific week on a specific day of the week of a month +(⪚, the 2nd Tuesday of March), or the day of the month in a +particular month of the year - <guilabel>Recur on day <replaceable>#</replaceable> +of the <replaceable>month</replaceable></guilabel>. By default, &korganizer; +assumes you mean the day of the month. You can adjust the period to +reflect events that occur bi-annually, every four years, and so on.</para> +</listitem> +</varlistentry> +</variablelist> +</sect3> + +<sect3 id="recurrence-recurrence-range"> +<title>Recurrence Range</title> + +<para>By default, events which repeat will do so forever; there is no +<quote>end</quote> to the repetition. This may or may not be desirable, +so you are provided with two ways of terminating the repetition: either +by giving an ending date, or by specifying a total number of +recurrences. In this area, you can choose the method that is suitable +for this event.</para> + +</sect3> + +<sect3 id="recurrence-exceptions"> +<title>Exceptions</title> + +<para>You may have a very nice recurrence rule set up, but realize that +there are a few exceptions. If you set up your college class schedule +for instance, you may want to make exceptions for holidays and the like. +In this area, you can add, change, and delete dates from the list of +exceptions (&ie; times when even if the recurrence rule matches, the +event will <emphasis>not be scheduled</emphasis>). Pick a date with the +date selector, and press <guibutton>Add</guibutton> to include it. For +removing dates, highlight them in the box on the right side, and then +click <guibutton>Delete</guibutton>.</para> + +<para>When you want to confirm, call off or revert the entered data, +choose among the <link linkend="reference-action-buttons">Action +Buttons</link>, <guibutton>OK</guibutton>, <guibutton>Apply</guibutton> +and <guibutton>Cancel</guibutton>.</para> +</sect3> +</sect2> + +<sect2 id="entering-data-events-attendees"> +<title><guilabel>Attendees</guilabel> Tab</title> + +<para>Chose in this tab the people you want to invite to your event.</para> + +<screenshot id="screenshot-event-attendees"> +<screeninfo>A screenshot of &korganizer;'s Edit Event dialog - Attendees tab</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="event-attendees.png" format="PNG"/></imageobject> +<textobject><phrase>A screenshot of &korganizer;'s Edit Event dialog - Attendees tab</phrase></textobject> +<caption><para>A screenshot of &korganizer;'s Edit Event dialog - Attendees tab</para></caption> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Identity as organizer:</guilabel></term> +<listitem><para>Sets the identity corresponding to the organizer of this to-do +or event. If &korganizer; is configured to send invitation mails, the identity +selected on this combo box will be used when sending these mails. The default +identity can be set in the <guilabel>Personal</guilabel> section of the +&korganizer; configuration, other identities in the <guilabel>Security & +Privacy</guilabel>-><guilabel>Password & User Account</guilabel> section +of the &kcontrolcenter;. In addition, identities are gathered from your &kmail; +settings and from your address book. If you choose to set it globally for &kde; +in the &kcontrolcenter;, be sure to check the <guilabel>Use email settings from +Control Center</guilabel>' box in the <guilabel>Personal</guilabel> section of +the &korganizer; configuration.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Attendee list</term> +<listitem><para>The list in the center of the tab displays the attendees +selected for this event, and lets you select attendees to edit or +remove. Please note that you can change the order of attendees. +Click any of the column headings (Name, Email, Role, Status, +<acronym>RSVP</acronym>) to sort the list according to that column. +The <acronym>RSVP</acronym> column indicates whether or not a response is +requested from the attendee.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Select Addressee</guibutton></term> +<listitem><para>If the attendee(s) are in your Address Book, you do not have to +remember or type his email address to add it to the attendee list. Just click +the <guibutton>Select Addressee...</guibutton> button and choose the attendee(s) +from the list. Please note that this is the standard &kde; address book, which +is also used by &kmail; and can also be called as a separate application +(&kaddressbook;).</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>New</guibutton></term> +<listitem><para>Press the <guibutton>New</guibutton> button to add a new +manually added attendee to the list. If you want to add contacts from your +address book, press <guibutton>Select Addressee</guibutton> instead. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Name</guilabel> field</term> +<listitem><para>Fill in the Attendee <guilabel>Name</guilabel> and +<guilabel>Email</guilabel> address fields, or select one of the attendees in +the list above to edit it.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Role</guilabel></term> +<listitem><para>Choose the role of the attendee (Participant, +Optional participant, Observer, Chair) from the drop down menu. The role is a +simple reminder of what part the attendee plays in this event. It can be used +for sorting (see above). +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Status</guilabel></term> +<listitem><para>Choose the status of the attendee (Needs Action, Accepted, +Declined, Tentative, Delegated, Completed, In progress). The status, which +is displayed in the details list window gives you quick overview of what +should be done to make the event successful. It can be used for sorting (see +above). If you use groupware schedule and request responses from your +attendees, as you receive the responses the status of the attendee will be +updated. If you don't request responses, you will have to update the status +manually.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Request Response</guilabel></term> +<listitem><para>Check the <guilabel>Request Response</guilabel> check box if +this attendee should respond to your schedule plan. Consequently the attendee +will be emailed with the event schedule information. A small envelope will +appear in the details list to indicate this. This feature is specially useful +when groupware scheduling is enabled, as the attendees status are updated +automatically.</para></listitem> +</varlistentry> + +</variablelist> + +<para>When you want to confirm, call off or revert the entered data, choose +among the <link linkend="reference-action-buttons">Action Buttons</link>, +<guibutton>OK</guibutton>, <guibutton>Apply</guibutton> and +<guibutton>Cancel</guibutton>.</para> + +</sect2> + +<sect2 id="entering-data-events-freebusy"> +<title><guilabel>Free/Busy</guilabel> Tab</title> + +<para>When adding attendees to your event, you need to know if they are +busy or free in that particular time. If the attendees make their free / +busy information available, you can view here their schedule before +sending the invitations.</para> + +<screenshot id="screenshot-event-freebusy"> +<screeninfo>A screenshot of &korganizer;'s Edit Event dialog - Free/Busy tab</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="event-freebusy.png" format="PNG"/></imageobject> +<textobject><phrase>A screenshot of &korganizer;'s Edit Event dialog - Free/Busy tab</phrase></textobject> +<caption><para>A screenshot of &korganizer;'s Edit Event dialog - Free/Busy tab</para></caption> +</mediaobject> +</screenshot> + +<para>This tab shows the free/busy schedule chart on the right, where each line +represents one of the attendees, listed on the left. The marked areas on the +chart represent the time already taken by other events, unmarked areas represent +time free from other events. You can move the event to a different point in time +by dragging it with the mouse, or resize it, by moving the edges of the highlighted +area with the mouse.</para> + +<para>The free/busy information is only available if the +attendee publishes his free/busy schedule, and if &korganizer; is correctly +configured to retrieve it. For more information about configuring &korganizer; +to publish and retrieve free/busy information, please check the +<xref linkend="config" />. Double-clicking on an attendee entry in the list +will allow you to enter the location of their free/busy information. +</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Scale</guilabel></term> +<listitem><para>Sets the zoom level on the schedule chart. <guilabel>Hour</guilabel> +shows a range of several hours, <guilabel>Day</guilabel> shows a range of a few +days, <guilabel>Week</guilabel> shows a range of a few months, and +<guilabel>Month</guilabel> shows a range of a few years, while +<guilabel>Automatic</guilabel> selects the range most appropriate for the +current event or to-do.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Center on Start</guibutton></term> +<listitem><para>Press this button to center the free/busy schedule chart on the +start time and day of this event.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Zoom to Fit</guibutton></term> +<listitem><para>Press this button to zoom the free/busy schedule chart so that you +can see the entire duration of the event on it.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Pick Date</guibutton></term> +<listitem><para>Press this button to automatically move the event to a date and +time when all the attendees are free.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Reload</guibutton></term> +<listitem><para>Press this button to reload Free/Busy data for all attendees +from the corresponding servers.</para></listitem> +</varlistentry> + +</variablelist> + +<para>When you want to confirm, call off or revert the entered data, choose +among the <link linkend="reference-action-buttons">Action Buttons</link>, +<guibutton>OK</guibutton>, <guibutton>Apply</guibutton> and +<guibutton>Cancel</guibutton>.</para> + +</sect2> + +<sect2 id="entering-data-events-attachments"> +<title><guilabel>Attachments</guilabel> Tab</title> + +<screenshot id="screenshot-event-attachments"> +<screeninfo>A screenshot of &korganizer;'s Edit Event dialog - Attachments tab</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="event-attachments.png" format="PNG"/></imageobject> +<textobject><phrase>A screenshot of &korganizer;'s Edit Event dialog - Attachments tab</phrase></textobject> +<caption><para>A screenshot of &korganizer;'s Edit Event dialog - Attachments tab</para></caption> +</mediaobject> +</screenshot> + +<para>Events and to-dos can contain attachments. Attachments can either be stored as links +or inline. The following actions are provided to work with attachments:</para> + +<variablelist> + +<varlistentry> +<term><guibutton>Add URI...</guibutton></term> +<listitem><para>Adds a link attachment.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Add File...</guibutton></term> +<listitem><para>Adds an inline attachment.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Edit...</guibutton></term> +<listitem><para>Allows to change an existing attachment.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Remove</guibutton></term> +<listitem><para>Deletes the selected attachment.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Show</guibutton></term> +<listitem><para>Display the selected attachment.</para></listitem> +</varlistentry> + +</variablelist> + +<para>When you want to confirm, call off or revert the entered data, choose +among the <link linkend="reference-action-buttons">Action Buttons</link>, +<guibutton>OK</guibutton>, <guibutton>Apply</guibutton> and +<guibutton>Cancel</guibutton>.</para> + +</sect2> + +<sect2 id="entering-data-events-template-buttons"> +<title><guilabel>Load/Save as Template</guilabel></title> + +<para>The <guilabel>Save as Template</guilabel> button enables you to save the +current event as a template, so that you can reuse the data entered for future +events. As an example you can save a template for a meeting that takes place at +the same location and with the same people.</para> +<para>With the <guilabel>Load Template</guilabel> button you can use an existing +template for your event. Continuing the example in the preceding paragraph you +can specify the agenda of the meeting.</para> + +</sect2> + +</sect1> + +<sect1 id="entering-data-to-do"> +<title>To-dos</title> + +<para>The To-do List is a place for you to write down notes to yourself about +things that you need to do. To-dos are tasks, that may or may not be +scheduled. There are short-term and long-term to-dos. For instance you should go +to a hairdresser within a week, and you should sell your old car within a +year. You likely do not want an alarm go off at a particular time, you just +want to have a list of things that you must do, and dates when they must be +finished at the latest (date due).</para> + +<para>To enter a new to-do, choose +<menuchoice><guimenu>Actions</guimenu><guimenuitem>New +To-do...</guimenuitem></menuchoice>. A window with <guilabel>General</guilabel>, +<guilabel>Recurrence</guilabel>, <guilabel>Attendees</guilabel>, and +<guilabel>Attachments</guilabel> tabs appears.</para> + +<sect2 id="entering-data-to-do-general"> +<title><guilabel>General</guilabel> Tab</title> + +<screenshot id="screenshot-todo-general"> +<screeninfo>A screenshot of &korganizer;'s Edit To-do dialog - General tab</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="todo-general.png" format="PNG"/></imageobject> +<textobject><phrase>A screenshot of &korganizer;'s Edit To-do dialog - General tab</phrase></textobject> +<caption><para>A screenshot of &korganizer;'s Edit To-do dialog - General tab</para></caption> +</mediaobject> +</screenshot> + +<variablelist> + +<varlistentry> +<term><guilabel>Title</guilabel></term> +<listitem><para>Enter short description of the to-do into the +<guilabel>Title</guilabel> field. This description is the text shown +on the &korganizer; <guilabel>To-do list</guilabel>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Location:</guilabel></term> +<listitem><para>Enter short description of the <guilabel>location</guilabel> +where the to-do will take place.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Date & Time</guilabel></term> +<listitem><para>The <guilabel>Due</guilabel> and <guilabel>Start</guilabel> +boxes are not initially checked, as to-dos usually do not have a start and due +date. Check one of both boxes and +change these dates as desired. Enter the dates directly or use the +<link linkend="glossary" endterm="gloss-calendar-widget">Calendar Widget</link>. +Choose time from quarter hour intervals, or enter the desired time directly into +the time fields. These fields are only available when <guilabel>Time associated</guilabel> +is checked.</para> +<tip><para>The date and time are initially unchecked, because to-dos do not +have the character of a fixed event. Some of them do not need a due date at +all. Most of them certainly do not need the exact time of fulfillment. If your +to-do requires exact time, maybe it actually belongs to <link +linkend="entering-data-events">events</link>.</para></tip></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Completed</guilabel></term> +<listitem><para> +This is a percent completed pull down menu initially set at 0% complete. +Later on, you can indicate your progress by adjusting the percent completed +in steps of 10%.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Priority</guilabel></term> +<listitem><para>Assign a priority to your to-do. This drop down menu offers +priorities from one to five, one being the highest. Initially to-dos are set +to priority five (medium).</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Reminder</guilabel></term> +<listitem><para>Check the <guilabel>Reminder</guilabel> box if +&korganizer; should remind you about the to-do.</para> +<!-- +<tip><para>&korganizer; can also run a specific program at that time. +Make sure, however, that you have sufficient rights to run that +program; if you do not, the program will not run.</para></tip>--> +<para>Choose how many minutes, hours or days before the to-do you want to be +reminded, or click the <guibutton>Advanced</guibutton> button to open the +<guilabel>Edit Reminders</guilabel> dialog. Using this dialog, you can set +repeating intervals for your reminders, and create special reminders that play +sounds, run programs, or send emails.</para> + +<!--Click the musical <guiicon>Note</guiicon> symbol to choose the +alarm sound. Click the <guiicon>Gear</guiicon> icon to browse for a +program that should run at the alarm time.</para>--></listitem> +</varlistentry> + + +<varlistentry> +<term>Details</term> +<listitem><para>Enter a long description of the to-do in the large +rectangle.</para> +<para>For example, If the to-do is, say, planned general repair of your car, +you can list all items that need repairing. Later on you can print this list +and hand it over to the serviceman. If the to-do is shopping, you should +list the goods that you need to buy. Print the to-do and take it to the +shop with you.</para> +</listitem></varlistentry> + +<varlistentry> +<term><guilabel>Select Categories</guilabel></term> +<listitem><para>You can assign several categories to a calendar item. Click the +<guilabel>Select Categories</guilabel> button to open the +<guilabel>Select Categories</guilabel> dialog. Check the category boxes to +assign suitable categories to the to-do. You can also add a new category, modify +a category or delete a category by pressing the button +<guilabel>Edit Category</guilabel>.</para> + +<tip><para>Your language lesson at work may belong to both Business +and Education categories, while the anniversary of your marriage belongs to +either Personal or Special Occasion - it is your choice.</para></tip> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Access</guilabel></term> +<listitem><para>Choose <guilabel>Private</guilabel> or <guilabel>Confidential</guilabel> +to keep the to-do private or confidential. Currently, this choice correctly +sets the <quote>CLASS</quote> attribute of the events or to-dos to +<quote>PUBLIC</quote>, <quote>PRIVATE</quote> or <quote>CONFIDENTIAL</quote>. +However, if these settings are really used to restrict the access of the information +depends on the client and / or groupware server implementation.</para> +<warning><para>Currently, &korganizer; <emphasis>will</emphasis> display +items owned by other people and marked as confidential. Other +clients may treat them differently, but be careful when publishing private or +confidential to-dos: vCalendar and iCalendar are text files, and can be read +with any text editor (if someone has read access to them). So if you want to +keep items really confidential, make sure you use a resource that +only you can access.</para></warning></listitem> +</varlistentry> +</variablelist> + +<para>When you want to confirm, call off or revert the entered data, choose +among the <link linkend="reference-action-buttons">Action Buttons</link>, +<guibutton>OK</guibutton>, <guibutton>Apply</guibutton> and +<guibutton>Cancel</guibutton>.</para> + +</sect2> + +<sect2 id="entering-data-to-do-recurrence"> +<title><guilabel>Recurrence</guilabel> Tab</title> + +<para>Some to-dos take place regularly. You can specify exact scheduling +here.</para> + +<note><para> If the to-do does not have a due date, this tab is completely +disabled. To activate the settings, start by checking the +<guilabel>Enable recurrence</guilabel> check box. If it is not checked, you are +not able to make any changes on this tab.</para></note> + +<para>The Recurrence tab window is divided into four groups: +<guilabel>Appointment Time</guilabel>, <guilabel>Recurrence Rule</guilabel>, +<guilabel>Recurrence Range</guilabel>, and <guilabel>Exceptions</guilabel>. +</para> + +<para>This tab is configure in the same way as the +<link linkend="entering-data-events-recurrence"><guilabel>Edit Event</guilabel> +dialog's <guilabel>Recurrence</guilabel> tab</link>. Please check +<xref linkend="entering-data-events-recurrence" /> for more information +about setting the recurrence options.</para> + +</sect2> + +<sect2 id="entering-data-to-do-attendees"> +<title><guilabel>Attendees</guilabel> Tab</title> + +<para>Some to-dos may require more people. You can list those people +here. Please check <xref linkend="entering-data-events-attendees" /> +for more information.</para> + +<para>When you want to confirm, call off or revert the entered data, +choose among the <link linkend="reference-action-buttons">Action +Buttons</link>, <guibutton>OK</guibutton>, +<guibutton>Apply</guibutton> and <guibutton>Cancel</guibutton>.</para> + +</sect2> + + +<sect2 id="entering-data-to-do-attachments"> +<title><guilabel>Attachments</guilabel> Tab</title> + +<para>Some to-dos require attachments. You can <guibutton>Add...</guibutton>, +<guibutton>Edit...</guibutton>, <guibutton>Remove</guibutton>, and +<guibutton>Show</guibutton> attachments. You can refer to the attachment by +entering the path to the attachment or Internet address.</para> + +<para>When you want to confirm, call off or revert the entered data, choose +among the <link linkend="reference-action-buttons">Action Buttons</link>, +<guibutton>OK</guibutton>, <guibutton>Apply</guibutton> and +<guibutton>Cancel</guibutton>.</para> + +</sect2> +</sect1> + +<sect1 id="entering-data-required-fields"> + +<title>Required Fields</title> + +<para>This is an overview of what fields are required and what fields can be +empty when entering events and to-dos:</para> + +<itemizedlist> +<listitem><para>In the <guilabel>General</guilabel> Tab, you should at least +fill the <guilabel>Title</guilabel> field and the description (the large +rectangle), even though neither is mandatory. If you check the +<guilabel>Reminder</guilabel> check box, you should also specify the time, and +either the sound to be played or the program to be run.</para></listitem> +<listitem><para>The <guilabel>Attendees</guilabel> tab may be left completely +empty.</para></listitem> +<listitem><para>The <guilabel>Recurrence</guilabel> tab must only be filled if +you checked the <guilabel>Enable Recurrence</guilabel> check box. +</para></listitem> +<listitem><para>The <guilabel>Attachments</guilabel> tab may be left completely +empty.</para></listitem> +</itemizedlist> +</sect1> +</chapter> + +<chapter id="group-scheduling"> +<title>Group Scheduling</title> + +<para>The group schedule functionality of &korganizer; allows you to +organize appointments, meetings and shared to-do items, request responses +from attendees and publish items. If you are being invited to an event or +to-do, you can reply to it, stating if you will be able to attend, or send a +counter proposal, with different arrangements, like a different time or +location. You can also publish your free/busy schedule, to let people know when +you are available, and request the same information from others.</para> + +<para>Currently, &korganizer; schedules events and to-dos using email to +transport the data, in a standards based scheme, the IMIP-protocol for group +scheduling. Being a standard, IMIP is a used by many other clients too. For +example &Microsoft;<application>Outlook</application>, Lotus +<application>Notes</application> and Novell +<application>Evolution</application>. This means that you can share +events with other users using one of these clients. +&korganizer; is integrated with &kmail; for receiving, processing, and sending +events, event responses, updates, cancellations, &etc; For instance, when you +get an invitation in &kmail;, and decide to +accept it, by clicking the the <guilabel>accept</guilabel> link in the mail +body, the event is added to your calendar, and a response to the event's +organizer is sent automatically.</para> + + +<!--TODO: check if to-dos work or not.--> +<!--TODO: check what happens if you counter without this option on.--> + +<para>If you check the <guilabel>Use Groupware Communication</guilabel> box +in the <link linkend="config-main-groupscheduling">&korganizer; group +scheduling configuration</link>, &korganizer; will handle the group scheduling +communication for you. In other words, you will seldom need to use the +<guimenu>Schedule</guimenu> menu directly to perform the scheduling actions. +For instance, if you <link linkend="entering-data-events">create an +event or to-do</link> with attendees, &korganizer; will ask you if you want to send the +invitations to the attendees, so you will not need to use the <menuchoice> +<guimenu>Schedule</guimenu><guimenuitem>Send Invitation to Attendees</guimenuitem> +</menuchoice> menu item later. Also, if you change your status as an attendee +for an event you were invited to, it will ask you if you want to send your updated +status to the event's organizer, so you will not need to use the <menuchoice> +<guimenu>Schedule</guimenu><guimenuitem>Send Status Update</guimenuitem> +</menuchoice> menu item later.</para> + + + +<sect1 id="publish"> +<title>Publishing an Event, To-do or Journal Entry</title> + +<para>If you simply want to send an event, to-do or journal entry, choose the +<menuchoice><guimenu>Schedule</guimenu><guimenuitem>Publish +Item Information...</guimenuitem></menuchoice> menu item, when the item is +selected. Then a dialog appears, asking you the email addresses which will +receive the event or to-do. The item will be sent by email, in the iCalendar +format.</para> + +<para>Please note that you can use this action to email any item to +anyone, not just to the item's attendees. In fact, you can publish an item with no +attendees at all, as publishing does not request an answer from the +attendees.</para> + +<para> +An example: you are playing in a band and, from time to time, you +give live concerts. To notify your fans about the concerts, you maintain +a mailing list. If you use &korganizer; to organize your concert dates, +you can just choose the <menuchoice><guimenu>Schedule</guimenu> +<guimenuitem>Publish Item Information...</guimenuitem></menuchoice> menu item, +put in the address of the mailing list and the event gets sent. Mailing +list subscribers who use &korganizer; get the concert date automatically +inserted in their calendar. +</para> + +<para>Publishing an event as described above will only inform the receiver about +the event, but not give her the option to ask for attendance. Use +<menuchoice><guimenu>Schedule</guimenu><guimenuitem>Send as iCalendar...</guimenuitem></menuchoice> +if you want to provide that option instead. +</para> + +</sect1> + + +<sect1 id="as-organizer"> +<title>Acting as Organizer in Group Scheduling</title> + +<para>When you create <link linkend="entering-data-events">an event</link> or +<link linkend="entering-data-to-do">a to-do</link>, and +<link linkend="entering-data-events-attendees">add attendees to it</link>, you +are acting as the event organizer. To add attendees, use the +<link linkend="entering-data-events-attendees"> +attendee tab</link>, in the <guilabel>Edit Event</guilabel>, or +<guilabel>Edit To-do</guilabel> dialog. In the +<link linkend="agenda-view">agenda view</link>, a little icon +<inlinemediaobject> +<imageobject> +<imagedata fileref="organizer.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>Organizer Icon</phrase> +</textobject> +</inlinemediaobject> +is placed in the event, if you are the +organizer of a group scheduling event.</para> + +<para>The organizer is responsible for sending the invitations, collecting +the attendees responses, and for keeping the data of the event or to-do up to +date for all people involved.</para> + +<sect2 id="request"> +<title>Sending Invitations and Processing Responses</title> + +<para>To organize an event or to-do, +<link linkend="entering-data-events">create it</link> in +&korganizer; and add all people that should attend using the +attendees tab. &korganizer; can send invitations to the +attendees, either automatically (depending on +<link linkend="config-main-groupscheduling">&korganizer; group +scheduling configuration</link>), or by selecting the event or to-do and +choosing the <menuchoice><guimenu>Schedule</guimenu><guimenuitem>Send Invitation +to Attendees</guimenuitem></menuchoice> menu item. +The attendees get an email containing all the relevant information +for the event or to-do. They can respond to the meeting proposal by accepting or +rejecting it or by making a counter proposal. They can also delegate or forward the +invitation. +All this information is sent to you by email again and, if you have configured &kmail; +appropriately the attendees responses are automatically inserted in your calendar. If +there are additional attendees willing to participate (e.g. by accepting a forwarded +invitation) you will be asked to accept the new attendees. +</para> + +</sect2> + +<sect2 id="cancel"> +<title>Cancelling an Event or To-do</title> + +<para>To cancel an event or to-do you have to be the organizer. If you +checked the <guilabel>Use Groupware Communication</guilabel> box +in the <link linkend="config-main-groupscheduling">&korganizer; group +scheduling configuration</link>, just delete the item, and &korganizer; will +ask you to send the cancellation. If not, simply select the +item, and choose the <menuchoice><guimenu>Schedule</guimenu> +<guimenuitem>Send Cancellation to Attendees</guimenuitem></menuchoice> +menu item.</para> + +<para>This action will send a cancel-message to all attendees, so +they can remove the item from their calendars too.</para> +</sect2> +</sect1> + + +<sect1 id="as-attendee"> +<title>Acting as the Attendee</title> + +<para>When you get an email with an invitation and accept it, the event or to-do +is added to your calendar. If it is an event, a little icon +<inlinemediaobject> +<imageobject> +<imagedata fileref="groupevent.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>Attendee Icon</phrase> +</textobject> +</inlinemediaobject> +is placed in the event in the <link linkend="agenda-view">agenda +view</link>.</para> + +<sect2 id="reply"> +<title>Answering an Invitation</title> + +<para>If you have an invitation in your &kmail; inbox you can either press +<guibutton>Reject</guibutton> to ignore the request, or press +<guibutton>Accept</guibutton> or <guibutton>Accept Cond.</guibutton>. The +last two actions will insert the item to your calendar. In any case, &kmail; will +send your response to the organizer automatically.</para> +<para>You can also <guibutton>Delegate</guibutton> or <guibutton>Forward</guibutton> +the invitation. When delegating, you can suggest another person as your proxy. +Using <guibutton>Forward</guibutton> you can forward the invitation to one or more +people not yet invited. +When the receiver of the delegation or forward accepts the invitation, +the organizer will be asked to approve the new attendee.</para> +<para>If for any reason you changed your mind, edit your status in the item's +<link linkend="entering-data-events-attendees">attendee tab</link>. If you +checked the <guilabel>Use Groupware Communication</guilabel> box +in the <link linkend="config-main-groupscheduling">&korganizer; group +scheduling configuration</link>, &korganizer; will ask you to send an email +updating your attendee status. If not, choose the <menuchoice> +<guimenu>Schedule</guimenu><guimenuitem>Send Status Update</guimenuitem> +</menuchoice> menu item to send your status update. +</para> +</sect2> + +<sect2 id="counter"> +<title>Sending an Alternative Proposal</title> + + +<para>If you are not satisfied with some of the characteristics of the event or +to-do you got invited to, and want to send a counter proposal to the organizer +(for instance an alternative location or time), just edit the item and send it +back as your proposal, by selecting the item and choosing the <menuchoice> +<guimenu>Schedule</guimenu><guimenuitem>Request Change</guimenuitem> +</menuchoice> menu item.</para> + +<para>The organizer of the event will get your proposal by email, and +will be able to accept it or decline.</para> +</sect2> + +<sect2 id="refresh"> + +<title>Requesting the Latest Version of an Event or To-do</title> + +<para>To request the latest version of an event or to-do, select +the item, and choose the <menuchoice><guimenu>Schedule</guimenu> +<guimenuitem>Request Update</guimenuitem></menuchoice> menu item. +The organizer should then send you back the latest version of the item.</para> + +</sect2> +</sect1> + +<sect1 id="free-busy"> +<title>Free Busy information</title> + +<para>The free/busy information represents an availability schedule. By +presenting the intervals when one already has previous commitments, +others can avoid arranging appointments for these periods. Note that only the +times are published, not the events, reasons or attendees.</para> + +<para>&korganizer; supports publishing and retrieving free/busy information, +either manually or automatically.</para> + +<para>To email your free/busy information, choose the <guimenu>Schedule</guimenu> +<guimenuitem>Mail Free Busy Information...</guimenuitem> menu item. Enter the +email addresses you want to send the information to in the dialog and press +<guilabel>OK</guilabel>.</para> + +<para>Groupware servers usually have a standard location for uploading +your free busy information, so that other users can access your data, and +you can access other user's free busy schedule. You can configure +&korganizer; to upload and download free busy information automatically, +using the <link linkend="config-main-views">Free Busy preferences</link>, +in the &korganizer; <guilabel>Configure</guilabel> dialog.</para> + +<para>To upload your free/busy information to the server set in &korganizer; +preferences, choose the <menuchoice><guimenu>Schedule</guimenu> +<guimenuitem>Upload Free Busy Information</guimenuitem></menuchoice> menu +item.</para> + +</sect1> + +<sect1 id="examples"> +<title>Examples</title> + +<sect2 id="examples-entering-event"> +<title>Entering a New Group Event</title> + +<para>In this example, you'll enter an event. You need to arrange a meeting on +<emphasis>the next Monday</emphasis> regarding launch of your new +Product. Your boss <emphasis>Joan Holden</emphasis> will be the event +chairwoman <emphasis>owner</emphasis>, and you, Jack Smith, will be the event +<emphasis>organizer</emphasis>. There will be two more +<emphasis>attendees</emphasis> (participants): <emphasis>Peter +Krzinski</emphasis> and <emphasis>Kirsten Friese</emphasis>. Joan gave you +the program of the meeting. The appointment will start at +<emphasis>12 noon</emphasis> and end at <emphasis>1 pm</emphasis>. The same +appointment should be scheduled <emphasis>(recurred)</emphasis> each Monday. +</para> + +<procedure> +<step><para>Using the Date Navigator, go to the next Monday.</para></step> + +<step><para>Choose the <menuchoice><guimenu>Actions</guimenu><guimenuitem>New +Event...</guimenuitem></menuchoice>, or select the area between +<emphasis>12 noon</emphasis> and end at<emphasis>1 pm</emphasis>, +and start typing the event title.</para></step> + +<step><para>Enter a suitable title. It's important to choose the right brief +description, because this is the only field that can be searched. We suggest +that you enter <userinput>Product launch event</userinput>.</para></step> + +<step><para>Enter the detailed event program into the largest rectangle +area. For the sake of this simple example, enter <userinput>Introduction, +The Plan, Conclusion</userinput> on three separate lines.</para></step> + +<step><para>Check the <guilabel>Reminder</guilabel> check box. Set the +reminder time to 15 minutes, just long enough to brew a cup of tea +prior to the meeting start.</para></step> + +<step><para>Click the <guilabel>Select Categories</guilabel> button.</para></step> + +<step><para>Check <guilabel>Appointment</guilabel> in the Available +Categories. Then click the +<guibutton>OK</guibutton> button.</para></step> + +<step><para>Click the <guilabel>Recurrence</guilabel> tab and check the +<guilabel>Enable recurrence</guilabel> box.</para> +<note><para>Most work has been done for you automatically. &korganizer; +defaults to recurring weekly. Also note that <guilabel>No ending date +</guilabel> is chosen. This means that this event will be repeated each +Monday (starting, of course, on Monday February 12, 2004) until the end of +time (that is, until you delete it).</para></note></step> + +<step><para>Since everything is all right here, click the +<guilabel>Attendees</guilabel> tab.</para></step> + +<step><para>In the <guilabel>Attendees</guilabel> tab you should do the +following:</para> +<substeps> + +<step><para>You will see that you are the organizer of the event. Click +the <guilabel>New</guilabel> button to add the other attendees.</para></step> + +<step><para>In the <guilabel>Name</guilabel> field, enter the email in the +<userinput>Name <email></userinput> format. In our example, enter +<userinput>Joan Holden <jholden@thiscompany.com></userinput>. +<tip><para>If the attendees are already in your &kde; address book, instead of typing the +names and emails, you can press the <guibutton>Select Addressee...</guibutton> +button to add them.</para></tip></para></step> + +<step><para>Choose <emphasis>Chair</emphasis> as the role.</para></step> + +<step><para>Click <guilabel>New</guilabel>.</para></step> + +<step><para>In the <guilabel>Name</guilabel> field, enter <userinput>Peter +Krzinski <pkrzinski@thiscompany.com></userinput>.</para></step> + +<step><para>Click <guilabel>New</guilabel>.</para></step> + +<step><para>In the <guilabel>Name</guilabel> field, enter +<userinput>Kirsten Friese <kfriese@thiscompany.com></userinput>. +</para></step> + +<step><para>Click <guilabel>Apply</guilabel>.</para></step> +</substeps> +</step> + +<step><para>If you have configured &korganizer; use groupware communication, +you will be asked if you want to send an email to the attendees, with details +of the event and asking for a response if the +<guilabel>Request response</guilabel> box from the +<guilabel>attendees</guilabel> tab is checked. Else, you can +send the invitations choosing the <menuchoice><guimenu>Schedule</guimenu> +<guimenuitem>Send Invitation to Attendees</guimenuitem></menuchoice> menu +item.</para></step> + +<step><para>Review the event +setup by clicking on the <guilabel>General</guilabel>, +<guilabel>Attendees</guilabel>, and <guilabel>Recurrence</guilabel> tabs. +If you are satisfied, click <guibutton>OK</guibutton>.</para></step> +</procedure> + +<para>Congratulations, you've scheduled your first event!</para> +</sect2> + +</sect1> + +</chapter> + +<chapter id="config"> +<title>&korganizer; Configuration</title> + +<para>To change &korganizer;'s look and behavior, choose the +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +&korganizer;...</guimenuitem></menuchoice> menu item, or if you are running +&korganizer; as the calendar component of &kontact;, choose the <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Calendar...</guimenuitem></menuchoice> menu item. You can get more information +about all the configure options and possibilities in +<xref linkend="config-main" />.</para> + +<para>To customize the set of tools available on the bar, choose the +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Toolbars... +</guimenuitem></menuchoice> menu item and read the <link +linkend="config-toolbars">configure toolbars detailed description</link>.</para> + +<para>To move toolbars around the screen, point your mouse over +the toolbar handle and drag the toolbar to a new position on your the +&korganizer; window.</para> + +<para>Localization information like date and time formats can be +configured from &kcontrolcenter; within the <menuchoice> +<guisubmenu>Regional & Accessibility</guisubmenu> <guimenuitem>Country/Region & +Language</guimenuitem> </menuchoice> module. This control module can be +accessed from within &korganizer;: just choose the <menuchoice><guimenu> +Settings</guimenu><guimenuitem>Configure Date & +Time...</guimenuitem></menuchoice> menu item. &korganizer; has to be restarted +for changes done in &kcontrolcenter; to take effect.</para> + +<para>To configure where &korganizer; stores and retrieves calendar events, +journal entries and to-dos, (in local files, groupware servers, journal entries as blogs, +network files, &etc;), please check <xref linkend="managing-resources" />.</para> + +<sect1 id="config-main"> +<title>&korganizer; Main Configuration</title> + +<para>The options dialog lets you configure a number of different areas of +&korganizer;.</para> + +<sect2 id="config-main-personal"> +<title>Personal</title> + +<para>The personal options relate to your personal identity, and other +miscellaneous things that don't fall under any of the other general +categories.</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Use email settings from control center</guilabel></term> +<listitem><para>Check this box to use your name and email address as set in +&kcontrolcenter; (<menuchoice><guimenuitem>Security & Privacy</guimenuitem> +<guimenuitem>Password & User Account</guimenuitem></menuchoice>).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Full name</guilabel></term> +<listitem><para><guilabel>Full name</guilabel> is initially set to +<quote>Anonymous</quote> with an email address of +<quote>nobody@nowhere</quote>. You can change your name by directly +entering it here or you can use your Email Settings from &kcontrolcenter; (see +above). This name will be displayed by default as +<guilabel>Organizer</guilabel> in to-dos and Events.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Email address</guilabel></term> +<listitem><para><guilabel>Email address</guilabel> will be used to identify the +owner of the calendar. When another person opens your calendar or events, he/she +will not be able to modify it because it will be read-only.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Export to &HTML; with every save</guilabel></term> +<listitem><para>By checking this option, you can order &korganizer; to export +your calendar and to-do list to an html file in your home folder every time you +save your changes.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Enable automatic saving of manually opened calendar files</guilabel></term> +<listitem><para>When this box is checked, +manually opened calendar files are saved automatically when you exit +&korganizer;, without asking. Furthermore, the calendar file is saved +periodically as you work to prevent the loss of valuable data. You can also +specify the save interval in minutes. + +<important><para>This option does not affect your +resource settings. To change the resource saving options, you have to configure +each resource individually. For more information about resources, please check +<xref linkend="managing-resources" />.</para></important> +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Confirm deletes</guilabel></term> +<listitem><para>When you check <guilabel>Confirm deletes</guilabel> box, + &korganizer; +will ask you to confirm each deletion. If this is not checked, &korganizer; +will not ask before deleting events.</para></listitem> +</varlistentry> + + +<varlistentry> +<term><guilabel>New Events, To-dos and Journal Entries Should</guilabel></term> +<listitem><para>This option lets you choose between adding new items to +the standard resource or making &korganizer; ask you which resource should be +used to save each new item.</para> +<para>Kolab2 server specificity: It is recommended to choose <guilabel>Be asked +which resource to use</guilabel>, if you intend to use the shared folder +functionality of the <guilabel>Kolab</guilabel> server. This +will allow you to keep control of which information is available only to you, and which information is published in the shared folders.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Default email attachment method</guilabel></term> +<listitem><para>This option allows you to select the way an email is attached to +an event. You can attach an email the complete email including attachments, the email +excluding attachments or only a link to the email.</para> +<para>Note that attaching an email without attachments might invalidate its signature. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="config-main-time-and-date"> +<title>Time & Date</title> + +<variablelist> +<varlistentry> +<term><guilabel>Timezone</guilabel></term> +<listitem><para>Select your location from the list on the drop +down. If your city is not listed, select one that shares the same time zone. +&korganizer; will automatically adjust for daylight savings.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use holiday region</guilabel></term> +<listitem><para>Select your country from the list on the drop down, or if +it is not listed, select <guilabel>(None)</guilabel>. +If your country is selected, &korganizer; will recognize and display +its important dates and holidays in the calendar view.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Day begins at</guilabel></term> +<listitem><para>Select the time you start your day from the list on the drop +down. It could be the time when you usually get up, or the time when you start +working. This setting does not prevent you to set or view items before +this time, it just sets the time that will be displayed by default on the top +of the calendar view. Use the scrollbar to display earlier or later events +in the agenda view.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Default appointment time</guilabel></term> +<listitem><para>Select the default start time for events from the list on +the drop down. When you choose <link linkend="menu-actions-new-event">New +Event</link> from the <link linkend="entering-data-events">Action Menu</link>, or +create an event in some other manner such that &korganizer; cannot guess +when you would like your event to start, &korganizer; will put this hour +in the start time editor as the default value.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Default duration of new appointment (HH:MM):</guilabel></term> +<listitem><para>Select the default duration for events using the spin box. When +you choose <link linkend="menu-actions-new-event">New Event</link> from the +<link linkend="entering-data-events">Action Menu</link>, or create an event in +some other manner such that &korganizer; cannot guess its duration, +&korganizer; will use this as the default value. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Default alarm time</guilabel></term> +<listitem><para>Select how long before the actual event's scheduled time will +the alarm activate.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Working Hours</guilabel></term> +<listitem><para>The options <guilabel>Daily start hour</guilabel> and +<guilabel>Daily ending hour</guilabel> let you specify when your working day starts +and when it ends. &korganizer; set the working hours apart by marking them +with a different color from the non working hours, holidays and non working +days.</para> +<para>Additionally, you have check boxes labeled after the days of the week. +Check the week days that are working days for you, in order to mark the working +hours in these days. Check <guilabel>Exclude holidays</guilabel> +prevent &korganizer; from marking the working hours for the holiday region +defined in the <guilabel>Use holiday region</guilabel> drop down above.</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="config-main-views"> +<title>Views</title> + +<para>These options let you configure &korganizer; views:</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Enable tooltips displaying summary of events</guilabel></term> +<listitem><para>If your summary for an event is longer than would fit in the +current View, the remaining characters are not displayed. Check <guilabel>Enable +tooltips displaying summary of events</guilabel> if you want the full summary +displayed when the hovering the mouse pointer over the appointment for a few +seconds.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show to-dos in day, week and month views</guilabel></term> +<listitem><para>This check box toggles the display of to-dos in the day, week +and month views in the agenda (day and week) and month views. If you have +too many to-dos which have due date associated, you may want to turn them +off to avoid clutter.</para></listitem> +</varlistentry> + +</variablelist> + +<para><link linkend="description-view">Date Navigator</link> options:</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Show events that recur daily in date navigator</guilabel></term> +<listitem><para>If the <guilabel>Show events that recur daily in date +navigator</guilabel> box is checked, the days containing daily recurring +events are shown in bold typeface in the date navigator.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show events that recur weekly in the date +navigator</guilabel></term> +<listitem><para>If the <guilabel>Show events that recur weekly in date +navigator</guilabel> box is checked, the days containing weekly recurring +events are shown in bold typeface in the date navigator.</para></listitem> +</varlistentry> + + +</variablelist> + +<para><link linkend="agenda-view">Agenda view</link> options:</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Hour size:</guilabel></term> +<listitem><para>By using this slider you can control the height of the rows +in the agenda view.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Next x days:</guilabel></term> +<listitem><para>This option allows you to change the amount of days of the +<guimenu>Next x Days</guimenu> menu item in the <guimenu>Views</guimenu> +menu.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show current-time (Marcus Bains) line</guilabel></term> +<listitem><para>This check box toggles a red line in the day or week view +indicating the current time (Marcus Bains line) on and off. This line gives +you an indication how much time is left ⪚ until a meeting takes +place.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show seconds on current-time line</guilabel></term> +<listitem><para>This check box toggles the seconds on the current-time +line (Marcus Bains line) on and off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Time range selection in agenda view starts event editor</guilabel></term> +<listitem><para>Check this box to start the event editor automatically when you +select a time range in the daily and weekly view. To select a time range, drag +the mouse from the start time to the end time of the event you are about to +plan.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Agenda view uses resource colors</guilabel></term> +<listitem><para>With &korganizer;, you can +<link linkend="config-main-colors">assign a different color to each +resource</link>. This check box toggles the use the resource color when +displaying the to-do or event in the agenda view on and off. Note that if you +don't assign different colors, there is little sense in using this feature, +as &korganizer; default configuration is to use the same color for +all resources.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Agenda view calendar display</guilabel></term> +<listitem><para> +Select if all calendars should be merged into one agenda view, each calendar should +be displayed in its own aganda view or if both view should be available via tabs. +</para></listitem> +</varlistentry> + +</variablelist> + +<para><link linkend="month-view">Month view</link> options:</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Enable scrollbars in month view cells</guilabel></term> +<listitem><para>This check box toggles the cell scrollbars in the +month view on and off. Even if you check this box, the scrollbars will +only appear when needed.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Month view uses full window</guilabel></term> +<listitem><para>If you check this box, the month view will be displayed +in the whole &korganizer; window instead of sharing the window with the sidebar +(the date navigator, the to-dos and the calendar resources).</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Month view uses category colors</guilabel></term> +<listitem><para>With &korganizer;, you can +<link linkend="config-main-colors">assign a different color to each +category</link>. If you check this box, the event or to-do color in the month +view will reflect the category color, instead of using no color, or only the +resource color. Note that if you don't assign different category colors, +there is little sense in using this feature, as &korganizer; default +configuration is to use the same color for all categories.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Month view uses resource colors</guilabel></term> +<listitem><para>With &korganizer;, you can +<link linkend="config-main-colors">assign a different color to each +resource</link>. If you check this box, the event or to-do color in the month +view will reflect the resource color, instead of using no color, or only the +category color. Note that if you don't assign different resource colors, there +is little sense in using this feature, as &korganizer; default configuration +is to use the same color for all resources.</para></listitem> +</varlistentry> + +</variablelist> + +<para><link linkend="todo-view">To-do view</link> options:</para> + +<variablelist> + +<varlistentry> +<term><guilabel>To-do list view uses full window</guilabel></term> +<listitem><para>If you enable this option, the to-do list view will be displayed +in the whole &korganizer; window instead of sharing the window with the sidebar +(the date navigator, the to-dos and the calendar resources).</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Record completed to-dos in journal entries</guilabel></term> +<listitem><para>If you check this box, &korganizer; will automatically add +a journal entry for every completed to-dos.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="config-main-fonts"> +<title>Fonts</title> + +<variablelist> + +<varlistentry> +<term><guilabel>Time bar</guilabel></term> +<listitem><para>Press this button to pick the font, font style and size for the +time bar.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Month view</guilabel></term> +<listitem><para>Press this button to pick the font, font style and size for the +month view.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Agenda view</guilabel></term> +<listitem><para>Press this button to pick the font, font style and size for the +agenda view (day, week and work week views).</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Current-time line</guilabel></term> +<listitem><para>Press this button to pick the font, font style and size for the +Marcus Bains line (a red line in the agenda view indicating the current +time).</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="config-main-colors"> +<title>Colors</title> + +<para>Choose the color used for holidays, for highlighting, and for specific +event categories. You can choose a different color for each category. Of course +too many colors may be confusing, so use common sense. The use of color +depend also on the <link linkend="config-main-views">view +preferences.</link></para> + +<variablelist> + +<varlistentry> +<term><guilabel>Holiday color</guilabel></term> +<listitem><para>This button opens the <guilabel>Select Color</guilabel> dialog, +allowing you to select the holiday color. The holiday color will be used for the +holiday name in the month view and the holiday number in the date +navigator.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Highlight color</guilabel></term> +<listitem><para>This button opens the <guilabel>Select Color</guilabel> dialog, +allowing you to select the highlight color. The highlight color will be used for +marking the currently selected area in your agenda and in the date +navigator.navigator.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Default event color</guilabel></term> +<listitem><para>This button opens the <guilabel>Select Color</guilabel> dialog, +allowing you to select the default event color. The default event color will +be used for events categories in your agenda and (depending on the settings) in +the month view. Note that you can specify a separate color for each event +category below.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Agenda view background color</guilabel></term> +<listitem><para>This button opens the <guilabel>Select Color</guilabel> dialog, +allowing you to select the agenda view background color.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Working hours color</guilabel></term> +<listitem><para>This button opens the <guilabel>Select Color</guilabel> dialog, +allowing you to select the agenda view.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>To-do due today color</guilabel></term> +<listitem><para>This button opens the <guilabel>Select Color</guilabel> dialog, +allowing you to select the to-do due today color.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>To-do overdue color</guilabel></term> +<listitem><para>This button opens the <guilabel>Select Color</guilabel> dialog, +allowing you to select the to-do overdue color.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Categories</guilabel></term> +<listitem><para>This group allows you to assign a color to each category. Select +a category in the drop down, and press the button to open the +<guilabel>Select Color</guilabel> dialog, allowing you to select the color for +that category. <link linkend="config-main-views">Depending on the view +preferences</link>, this color will be used to mark events and to-dos which +belong to this category in your agenda and in the month view.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Resources</guilabel></term> +<listitem><para>This group allows you to assign a color to each resource. Select +a resource in the drop down, and press the button to open the +<guilabel>Select Color</guilabel> dialog, allowing you to select the color for +that resource. <link linkend="config-main-views">Depending on the view +preferences</link>, this color will be used to mark events and to-dos which are +stored using this resource in your agenda and in the month +view.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="config-main-groupscheduling"> +<title>Group Scheduling</title> + +<variablelist> + +<varlistentry> +<term><guilabel>Use Groupware Communication</guilabel></term> +<listitem><para>Check this box to automatically send mails when creating, +updating or deleting events or to-dos which involve others. This mail can be +an invitation to attendees of an event you created, a cancellation of an event +you created, an answer or an update on your invitation status, an event change +request, &etc; Check this option if you you want to use the groupware +functionality (e.g Configuring &kontact; as a &kde; +<guilabel>Kolab</guilabel> client).</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Send copy to owner when mailing events</guilabel></term> +<listitem><para>When you check the <guilabel>Send copy to owner when mailing +events</guilabel> box, you will get a copy of all email messages that +&korganizer; sends at your request to the event attendees.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Mail Client</guilabel></term> +<listitem><para>Here you can choose which type of mail transport you would like +to use. You can either use &kmail; or the &Sendmail; command (which must be +installed on your system in order to work).</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Additional email addresses</guilabel></term> +<listitem><para>This tells &korganizer; what further email addresses you have. +You can add, edit or remove additional emails addresses. These email addresses +are the ones you have in addition to the one set in +<link linkend="config-main-personal">personal preferences</link>. +If you get an invitation to an event, but use another email address there, you +need to list this address here so &korganizer; can recognize it as yours, and +add the item to your calendar. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<!-- +<sect2 id="config-main-groupautomation"> +<title>Group Automation</title> + +<variablelist> + +<varlistentry> +<term><guilabel>Auto Send Refresh</guilabel></term> +<listitem><para>to be written... +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Auto Insert IMIP Replies</guilabel></term> +<listitem><para>to be written... +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Auto Insert IMIP Requests</guilabel></term> +<listitem><para>to be written... +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Auto Send FreeBusy information</guilabel></term> +<listitem><para>to be written... +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>AutoSave FreeBusy Replies</guilabel></term> +<listitem><para>to be written... +</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> +--> + +<sect2 id="config-main-free-busy"> +<title>Free/Busy</title> + +<para>The free/busy information represents an availability schedule. By +presenting the intervals when one already has previous commitments, +others can avoid arranging appointments for these periods. Note that only the +times are published, not the events, reasons or attendees.</para> + +<para>&korganizer; supports publishing and retrieving free/busy information, +either manually or automatically.</para> + +<para><guilabel>Publish Tab</guilabel>: by publishing your free/busy +information, you allow others to take your busy time schedule into account +when inviting you to an event.</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Publish free/busy information</guilabel></term> +<listitem><para>Enable this option if you wish your Free/Busy information to be +uploaded automatically. Note that you may skip this option and choose to mail or +upload your Free/Busy information via the <guilabel>Schedule</guilabel> menu of +&korganizer;.</para> + +<para>If your application is setup to work as a <guilabel>&kde; Kolab +client</guilabel>, this is not required. The <guilabel>Kolab2</guilabel> server +can take care of publishing your Free/Busy information and manage the access to +it from other users.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Minimum time between uploads in minutes</guilabel></term> +<listitem><para>In case you choose to publish your information automatically, +you may configure the interval of time in minutes between each upload.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Publish (default 60) days of free/busy</guilabel></term> +<listitem><para>Configure the number of calendar days you wish to be published +and available to others</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Server &URL;</guilabel></term> +<listitem><para>Enter the &URL; for the server on which your Free/Busy information +shall be published. Ask the server administrator for this information.</para> +<para>Kolab2 server example: +<userinput>webdavs://kolab2.com/freebusy/joe@kolab2.com.ifb</userinput> +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Username</guilabel></term> +<listitem><para>Enter the login information relative to your account on the server</para> +<para>Kolab2 server specificity: Registered your UID (Unique IDentifier), by +default your UID would be similar to your email address on the Kolab2 server +but it may also be different. In the last case enter your UID. Ask about your +UID to the server administrator if you don't know it.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Password</guilabel></term> +<listitem><para>Enter here your password (server login password).</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Remember password</guilabel></term> +<listitem><para>Check this option if you want &korganizer; to remember your +password and skip asking you each time it upload your Free/Busy +information.</para> +<warning><para>It is not recommended to store your password in the configuration +file for security reasons.</para></warning></listitem> +</varlistentry> + +</variablelist> + +<para><guilabel>Retrieve Tab</guilabel>: by retrieving other peoples' free/busy +information, you can take their busy time schedule into account +when inviting them to an event.</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Retrieve other peoples' free/busy information +automatically</guilabel></term> +<listitem><para>Automate the process for retrieving other users free/busy time. +Fill in the server information section below to enable this +option.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use full email address for retrieval</guilabel></term> +<listitem><para>This setting lets you change the name of the file which will be +fetched from the server. If you check this option, it will download a free/busy +file called <userinput>user@domain.ifb</userinput>, else it will fetch +<userinput>user.ifb</userinput>. Ask the server Administrator if you are not +sure about how to configure this option.</para> +<para><guilabel>Kolab2 server specificity:</guilabel> If you are configuring +&korganizer; as a component to a <guilabel>&kde; Kolab client +(&kontact;/Kolab)</guilabel> you have to check this option.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Server &URL;</guilabel></term> +<listitem><para>Enter the &URL; for the server on which your Free/Busy information +shall be fetched. Ask the server administrator for this information.</para> +<para><guilabel>Kolab2 server example: +</guilabel><userinput>webdavs://kolab2.com/freebusy/</userinput> +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Username</guilabel></term> +<listitem><para>Enter the login information relative to your account on the +server.</para> +<para><guilabel>Kolab2 server specificity:</guilabel> Registered your UID +(Unique IDentifier), by default your UID would be similar to your email address +on the <guilabel>Kolab2 server</guilabel> but it may also be different. In the +last case enter your UID. Ask about your UID to the server administrator if you +don't know it.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Password</guilabel></term> +<listitem><para>Enter here your password (server login password). +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Remember password</guilabel></term> +<listitem><para>Check this option if you want &korganizer; to remember your +password and skip asking you each time it fetches the free/busy files.</para> +<warning><para>It is not recommended to store your password in the +configuration file for security reasons.</para></warning> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="config-main-plugins"> +<title>Plugins</title> + +<para>For more information about configuring plugins, please refer to +<xref linkend="plugins-chapter" /></para> + +</sect2> + +</sect1> + +<sect1 id="config-toolbars"> +<title>Toolbars Configuration</title> + +<para>&korganizer; has three toolbars: a Main toolbar (with +<guiicon>New Event</guiicon>, <guiicon>New To-do</guiicon>, +<guiicon>Print</guiicon>, <guiicon>Undo</guiicon>, <guiicon>Redo</guiicon>, +<guiicon>Cut</guiicon>, <guiicon>Copy</guiicon>, <guiicon>Paste</guiicon>, +<guiicon>Find</guiicon>, <guiicon>Go Backward</guiicon>, +<guiicon>Go Forward</guiicon> and +<guiicon>Goto Today</guiicon> buttons), a +<guiicon>Views</guiicon> toolbar (for selecting between +<guiicon>Whats Next view</guiicon>, +<guiicon>List view</guiicon>, <guiicon>Day view</guiicon>, +<guiicon>Work Week view</guiicon>, <guiicon>Week view</guiicon>, +<guiicon>Next X Day view</guiicon>, <guiicon>Month view</guiicon>, + <guiicon>To-do List view</guiicon> and <guiicon>Journal view</guiicon> +buttons), a Schedule toolbar (with <guiicon>Publish Item Information</guiicon>, +<guiicon>Send Invitations to Attendees</guiicon>, <guiicon>Send +Status Update</guiicon> and <guiicon>Open Address Book</guiicon> buttons) and a +Filters toolbar, which allows you to choose a filter for the &korganizer; views. +You can customize these toolbars in various ways: you can add new icons, +change the icon size, change toolbar position and add text description +to the icons.</para> + +<para>There are two ways to change the position of the toolbars: +<itemizedlist> +<listitem><para> +You can right click the toolbar to bring up the <guimenu>Toolbar Menu</guimenu>. +The icon size and text position can also be adjusted from this menu. +</para></listitem> +<listitem><para> +You can simply drag the toolbar by the handle on the left border of each +toolbar, and drop it whenever you wish. Also look at other easy <link +linkend="other-features-drag-and-drop">drag-and-drop operations</link>. +</para></listitem></itemizedlist> +</para> + +<para>The toolbars are configured in two places: +<itemizedlist> +<listitem><para>The tool set is configured in the <menuchoice><guimenu> +Settings</guimenu><guimenuitem>Configure +Toolbars....</guimenuitem></menuchoice> menu item. +</para></listitem> +<listitem><para>The graphic style (icon size, text position, &etc;) is +adjusted through the <guimenu>Toolbar Context Menu</guimenu>. Right click the +toolbar to access this menu. +</para></listitem> +</itemizedlist> +</para> + +<sect2 id="config-toolbars-settings-config"> +<title>Configure Toolbars Dialog</title> + +<para>This dialog allows you to customize the selection of tools on the +toolbar. Open it choosing the <menuchoice><guimenu>Settings</guimenu><guimenuitem> +Configure Toolbars...</guimenuitem></menuchoice> menu item.</para> + +<sect3 id="config-toolbars-choose-toolbar"> +<title>Choosing the toolbar</title> + +<para>First you need to choose the toolbar that you want to modify. All actions +apply to the toolbar that is selected from the drop down menu at the top of +the window.</para> +</sect3> + +<sect3 id="config-toolbars-available-actions"> +<title>Available Actions</title> + +<para>There are two rectangles below the toolbar title: <guilabel>Available +actions</guilabel> and <guilabel>Current actions</guilabel>. Using the left and +right arrows (located between the rectangles) you can add icons from the +Available actions group to the <guilabel>Current actions</guilabel> group. The +toolbar will have every icon that is in the <guilabel>Current action</guilabel> +box. The up and down arrows allow you reposition an icon.</para> + +<tip><para>Remember that less icons may be better, because the screen is less +busy and therefore it is easier to find the toolbar buttons you actually use. +For instance if you always cut and paste with the keyboard hotkeys, you do not +need the <guiicon>Cut</guiicon>, <guiicon>Copy</guiicon> and +<guiicon>Paste</guiicon> icons.</para></tip> + +</sect3> +</sect2> + +<sect2 id="config-toolbars-context-menu"> +<title>Toolbar Context Menu</title> + +<para>This menu allows you to change the look of the toolbars. +<mousebutton>Right</mousebutton> click the toolbar to access this +menu.</para> + +<sect3 id="config-toolbars-text-position"> +<title>Text Position</title> + +<para>Initially, icons do not have any text assigned. You may prefer +having text under each icon, or text alongside each icon. You can also have +plain texts without any icons.</para> +</sect3> + +<sect3 id="config-toolbars-toolbar-position"> +<title>Orientation</title> + +<para>You can have the toolbar at the top, bottom, left or right side. If you +choose Floating position, the toolbar will be displayed outside the main +&korganizer; panel and you can move it around. If you choose Flat, the toolbar +will collapse into a tiny rectangle. You can later click that rectangle and the +toolbar will appear again.</para> +</sect3> + +<sect3 id="config-toolbars-icon-size"> +<title>Icon Size</title> + +<para>You can change the size of the icons. Make your choice between small, +medium and large icons.</para> +</sect3> +</sect2> +</sect1> + +<!-- +<sect1 id="reference-windows-outgoing"> +<title>Outgoing Messages</title> +<para>to be written</para> +</sect1> + +<sect1 id="reference-windows-incoming"> +<title>Incoming Messages</title> +<para>to be written</para> +</sect1> +--> + + +</chapter> + +&plugins-chapter; + +<chapter id="reference"> +<title>Reference</title> + +<sect1 id="reference-menus"> +<title>Menus</title> + +<para>When &korganizer; starts, the main &korganizer; window +appears. The window has several components: a menubar, a toolbar, a +month calendar, a main panel with the current <quote>view</quote> of +events, and a to-do list.</para> + +<para>The menus provide access to all the common operations that can be +performed with the calendar, including saving, loading, adding and +deleting events, to-dos and journal entries, printing and more.</para> + +<para>Please note that when using &korganizer; as the calendar component +of &kontact;, the menus differ from the stand alone application.</para> + +<sect2 id="reference-menus-file"> +<title><guimenu>File</guimenu></title> + +<para>The <guimenu>File</guimenu> menu provides access to functions involving +the entire calendar.</para> + +<variablelist> + +<varlistentry id="menu-file-new"> +<term><menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo> +</shortcut> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_file_new.png" + format="PNG"/></imageobject></inlinemediaobject> +File</guimenu> <guimenuitem>New</guimenuitem></menuchoice></term> +<listitem> + +<para><action>Opens another main window.</action> This window initially +contains unnamed calendar. You can use the new window to:</para> + +<itemizedlist> +<listitem><para>open the same calendar twice (select the +<menuchoice><guimenu>File</guimenu><guimenuitem>Open</guimenuitem></menuchoice> +menu item and choose the same calendar as in the original window)</para></listitem> +<listitem><para>have two different calendars open at the same time (select the +<menuchoice><guimenu>File</guimenu><guimenuitem>Open</guimenuitem></menuchoice> +menu item and choose a different calendar). </para></listitem> +<listitem><para>create a new calendar (select the +<menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice> +menu item to give your new calendar a filename and to save it).</para></listitem> +</itemizedlist> + +<para>For more information about this acton, please refer to +<xref linkend="managing-import-export" />.</para> + +</listitem> +</varlistentry> + +<varlistentry id="menu-file-open"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo> +</shortcut> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_file_open.png" + format="PNG"/></imageobject></inlinemediaobject> +File</guimenu> <guimenuitem>Open</guimenuitem></menuchoice></term> +<listitem><para><action>Opens a file dialog allowing you to select a new +vCalendar or iCalendar file to load.</action> If you have made changes to the +current calendar, you will be given the option of saving them before loading a +new one.</para> +<para>For more information about this, please refer to +<xref linkend="managing-import-export" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-file-open-recent"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_file_open.png" + format="PNG"/></imageobject></inlinemediaobject>File</guimenu> +<guimenuitem>Open Recent</guimenuitem> +</menuchoice></term> +<listitem><para><guimenuitem>Open Recent</guimenuitem> <action>provides +a list of recently opened calendar files for quick access, allowing you to +bypass the file dialog entirely.</action></para> +<para>For more information about this action, please refer to +<xref linkend="managing-import-export" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-file-save"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo> +</shortcut> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_file_save.png" + format="PNG"/></imageobject></inlinemediaobject> +File</guimenu> <guimenuitem>Save</guimenuitem></menuchoice></term> +<listitem><para>When you choose <guimenuitem>Save</guimenuitem> or click the +<guiicon>Save</guiicon> icon, &korganizer; <action>saves the calendar to +disk, and makes sure all changes that you made will be +remembered</action>. If the calendar has no name, Save will behave like +<guilabel>Save As</guilabel>.</para> +<para>For more information about this action, please refer to +<xref linkend="managing-import-export" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-file-save-as"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_file_saveas.png" + format="PNG"/></imageobject></inlinemediaobject> +File</guimenu> +<guimenuitem>Save As...</guimenuitem> +</menuchoice></term> +<listitem><para><guilabel>Save As</guilabel> <action>displays a file dialog in +which you may choose a different name for your calendar than the one currently +assigned to it</action>. This is useful if you have made changes to a calendar +that you want to save, but also want to keep separate from your +<quote>regular</quote> calendar.</para> +<para>For more information about this action, please refer to +<xref linkend="managing-import-export" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-file-revert"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_file_revert.png" + format="PNG"/></imageobject></inlinemediaobject> +File</guimenu> <guimenuitem>Revert</guimenuitem></menuchoice></term> +<listitem><para>When you choose <guimenuitem>Revert</guimenuitem>, &korganizer; +<action>loads the last saved version of the calendar, discarding all the +changes made after the last save.</action>.</para> +<para>For more information about this action, please refer to +<xref linkend="managing-import-export" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-file-print"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo> +</shortcut> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_file_print.png" + format="PNG"/></imageobject></inlinemediaobject> +File</guimenu> <guimenuitem>Print</guimenuitem></menuchoice></term> +<listitem><para>Choose <guimenuitem>Print</guimenuitem> or click the +<guilabel>Print</guilabel> icon to <action>print the current +calendar</action>. You can specify the range of dates to be printed (either +manually or with Calendar Widget) and the Print Style (Day, Week, Month or +To-dos and Journal).</para></listitem> +</varlistentry> + +<!--<varlistentry id="menu-file-print-preview"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject> +<imagedata fileref="i_file_print_preview.png" +format="PNG"/></imageobject></inlinemediaobject> +File</guimenu><guimenuitem>Print Preview</guimenuitem></menuchoice></term> +<listitem><para>If you choose <guimenuitem>Print Preview</guimenuitem> or click +the <guiicon>Print Preview</guiicon> icon, <action>the current calendar will be +printed on your screen, instead of on your printer</action>. Use this +feature to check if the printout will be correct before you start +printing.</para> +<para>You can specify the range of dates to be printed (either manually or with +Calendar Widget) and the View Type (Day, Week, Month or To-do).</para> +</listitem> +</varlistentry>--> + +<varlistentry id="menu-file-import-calendar"> +<term><menuchoice> +<guimenu>File</guimenu> +<guisubmenu>Import</guisubmenu> +<guimenuitem>Import Calendar</guimenuitem> +</menuchoice></term> +<listitem><para>If you have a different iCalendar or +vCalendar file somewhere, and you would like to <action>merge its contents +into your own calendar, add as a new resource or open it as a new window</action>, +choose this menu item. A good time to do this would be if you received a +vCalendar with a few entries via email, for instance.</para> +<para>For more information about this action, please refer to +<xref linkend="managing-import" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-file-import-ical"> +<term><menuchoice> +<guimenu>File</guimenu> +<guisubmenu>Import</guisubmenu> +<guimenuitem>Import From &UNIX; Ical Tool</guimenuitem> +</menuchoice></term> +<listitem><para>If you have used <application>ical</application>, a popular but +older calendar program for &UNIX;, you may wish to <action>import your events, +events, and to-do</action> directly to &korganizer;. This action +will read the <filename>.calendar</filename> file from your home +folder and merge any entries it contains into your current calendar. +If any errors or suspicious things occur during the process, you will be +notified via a message box.</para> +<para>For more information about this action, please refer to +<xref linkend="managing-import" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-file-import-ghns"> +<term><menuchoice> +<guimenu>File</guimenu> +<guisubmenu>Import</guisubmenu> +<guimenuitem>Get Hot New Stuff...</guimenuitem> +</menuchoice></term> +<listitem><para>This action will open the <guilabel>Get Hot New Stuff</guilabel> +dialog, which offers a list of calendars to download. These events can be +added to your calendar.</para> +<para>For more information about this action, please refer to +<xref linkend="managing-get-hot-new-stuff" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-file-export-as-web"> +<term><menuchoice> +<guimenu>File</guimenu> +<guisubmenu>Export</guisubmenu> +<guimenuitem>Export Web Page...</guimenuitem> +</menuchoice></term> +<listitem><para><action>You can export your calendar or a part of it as a &HTML; +file, suitable for publishing on the World Wide Web.</action></para> +<para>For more information about this action, please refer to +<xref linkend="managing-export" />.</para></listitem> +</varlistentry> + +<varlistentry id="menu-file-export-icalendar"> +<term><menuchoice> +<guimenu>File</guimenu> +<guisubmenu>Export</guisubmenu> +<guimenuitem>iCalendar</guimenuitem> +</menuchoice></term> +<listitem><para>This action will export all your active events, to-dos and +journal entries (independent of to what resource they belong) as a new iCalendar +file.</para> +<para>For more information about this action, please refer to +<xref linkend="managing-export" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-file-export-vcalendar"> +<term><menuchoice> +<guimenu>File</guimenu> +<guisubmenu>Export</guisubmenu> +<guimenuitem>vCalendar</guimenuitem> +</menuchoice></term> +<listitem><para>This action will export all your active events, to-dos and +journal entries (independent of to what resource they belong) as a new vCalendar +file.</para> +<para>For more information about this action, please refer to +<xref linkend="managing-export" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-file-export-ghns"> +<term><menuchoice> +<guimenu>File</guimenu> +<guisubmenu>Export</guisubmenu> +<guimenuitem>Upload Hot New Stuff...</guimenuitem> +</menuchoice></term> +<listitem><para>This action will open the <guilabel>Upload Hot New Stuff</guilabel> +dialog, which allow you to export calendars containing events which may be +useful to other people, such as a conference program, a list of holidays, +special events, &etc;</para> +<para>For more information about this action, please refer to +<xref linkend="managing-get-hot-new-stuff" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-file-archive-old"> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Archive Old Entries...</guimenuitem> +</menuchoice></term> +<listitem><para><action>From time to time you should delete your old +events.</action></para> +<para>For more information about this action, please refer to +<xref linkend="managing-purge-archive" />.</para> +</listitem> +</varlistentry> + +<!--<varlistentry id="menu-file-make-active"> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Make active</guimenuitem> +</menuchoice></term> +<listitem><para>If you opened more than one calendar, only one calendar can +display alarms; only one calendar can be active. Click the <guilabel>Make +active</guilabel> menu item to <action>activate the current calendar +window.</action></para> +<para>The active calendar is loaded as default calendar when starting +&korganizer;. In other words, if you work with more than one calendar, you +should make your main calendar active.</para></listitem> +</varlistentry> + +<varlistentry id="menu-file-addressbook"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_file_addressbook.png" + format="PNG"/></imageobject></inlinemediaobject>File</guimenu> +<guimenuitem>Addressbook</guimenuitem> +</menuchoice></term> +<listitem><para>This action will open the address book browser in a new +window.</para></listitem> +</varlistentry> +--> + +<varlistentry id="menu-file-purge"> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Purge Completed To-dos</guimenuitem> +</menuchoice></term> +<listitem><para>This action will remove all the completed to-dos from your +active calendar.</para> +<para>For more information about this action, please refer to +<xref linkend="managing-purge-archive" />.</para> +</listitem></varlistentry> + +<!-- +<varlistentry id="menu-file-close"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo> +</shortcut> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_file_close.png" + format="PNG"/></imageobject></inlinemediaobject> +File</guimenu> <guimenuitem>Close</guimenuitem></menuchoice></term> +<listitem><para><action>Closes the current calendar. The window itself will +remain open, and may be reused to open another +calendar.</action></para></listitem> +</varlistentry> +--> + +<varlistentry id="menu-file-quit"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> +</shortcut> +<guimenu><inlinemediaobject><imageobject><imagedata + fileref="i_file_quit.png"/></imageobject></inlinemediaobject> File</guimenu> +<guimenuitem>Quit</guimenuitem> +</menuchoice></term> +<listitem><para>When you choose <guimenuitem>Quit</guimenuitem> or click +the <guiicon>Quit</guiicon> icon, <action>the current calendar window will quit, +prompting you to save if the current calendar has been modified but not yet +saved.</action></para> +<para>This has no effect on other calendar windows which may be opened. You have +to quit each calendar window individually.</para> </listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="reference-menus-edit"> +<title>Edit</title> + +<para>With the <guilabel>Edit</guilabel> menu you can edit and search events and +to-dos.</para> + +<para><guimenuitem>Cut</guimenuitem>, <guimenuitem>Copy</guimenuitem>, and +<guimenuitem>Paste</guimenuitem> menu items behave in the same fashion as in + other +&kde; applications. With the <guimenuitem>Find</guimenuitem> menu item you can +find event and to-dos across the current calendar.</para> + +<variablelist> + +<varlistentry id="menu-edit-undo"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo> +</shortcut> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_edit_undo.png" + format="PNG"/></imageobject></inlinemediaobject> +Edit</guimenu> <guimenuitem>Undo</guimenuitem> </menuchoice></term> +<listitem><para><action>Undo the latest action</action>, or in other words, +return the calendar to the state it was immediately before the latest +action.</para></listitem> +</varlistentry> + +<varlistentry id="menu-edit-redo"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo> +</shortcut> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_edit_redo.png" + format="PNG"/></imageobject></inlinemediaobject> +Edit</guimenu> <guimenuitem>Redo</guimenuitem> </menuchoice></term> +<listitem><para><action>Redo the latest action</action>, or in other words, +return the calendar to the state it was immediately before the latest +undo.</para></listitem> +</varlistentry> + +<varlistentry id="menu-edit-cut"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo> +</shortcut> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_cut.png" + format="PNG"/></imageobject></inlinemediaobject> +Edit</guimenu> <guimenuitem>Cut</guimenuitem> </menuchoice></term> +<listitem><para><action>Cuts the currently selected event(s) to the clipboard, +removing them from your calendar.</action></para></listitem> +</varlistentry> + +<varlistentry id="menu-edit-copy"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo> +</shortcut> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_copy.png" + format="PNG"/></imageobject></inlinemediaobject> +Edit</guimenu> <guimenuitem>Copy</guimenuitem></menuchoice></term> +<listitem><para><action>Copies the currently selected item(s) to the +clipboard, but leaving them untouched.</action></para></listitem> +</varlistentry> + +<varlistentry id="menu-edit-paste"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>V</keycap></keycombo> +</shortcut> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_paste.png" + format="PNG"/></imageobject></inlinemediaobject> +Edit</guimenu> <guimenuitem>Paste</guimenuitem></menuchoice></term> +<listitem><para><guimenuitem>Paste</guimenuitem> <action>inserts the +contents of the clipboard into your calendar</action>. The clipboard must +contain a valid vCalendar or iCalendar, provided either by a previous Cut/Copy +operation or from a selection made outside of &korganizer;. You will be warned +if the contents of the clipboard cannot be understood.</para> +<tip><para>However, you can safely use <keycombo action="simul">&Ctrl; +<keycap>C</keycap></keycombo> and <keycombo action="simul">&Ctrl; +<keycap>V</keycap></keycombo> hotkeys to copy text data from any outside +application to a &korganizer; Edit Event window and vice +versa. </para></tip></listitem> +</varlistentry> + +<varlistentry id="menu-edit-delete"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_edit_delete.png" + format="PNG"/></imageobject></inlinemediaobject> +Edit</guimenu> <guimenuitem>Delete</guimenuitem> </menuchoice></term> +<listitem><para><action>Delete the currently selected item(s), +removing them from your calendar.</action></para></listitem> +</varlistentry> + +<varlistentry id="menu-edit-find"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>f</keycap></keycombo> +</shortcut> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_edit_find.png" + format="PNG"/></imageobject></inlinemediaobject> +Edit</guimenu> <guimenuitem>Find</guimenuitem> +</menuchoice></term> +<listitem><para>Choose <guimenuitem>Find</guimenuitem> from the +<guimenu>Edit</guimenu> or click the <guiicon>Find</guiicon> icon to +<action>find events, to-dos and journal entries according to their title, +description, and/or categories</action>.</para> +<para>For more information about this action, please refer to +<xref linkend="search-view" />.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="reference-menus-view"> +<title><guimenu>View</guimenu></title> + +<para>There are several different <quote>views</quote> available for +displaying your events, to-dos and journal entries. &korganizer; is smart +enough to remember in between sessions what the last active view was, and the +next time it is started, it will display that view.</para> + +<para>In general, each view will provide a way of displaying your journal +entries, to-dos and and events, constrained to a particular time period or +style of display. Click any item to select it for further action. +<mousebutton>Right</mousebutton> click an item to bring up a menu +with options such as <guimenuitem>edit</guimenuitem>, +<guimenuitem>delete</guimenuitem>, and so on. You can also use the +<guimenu>Action</guimenu> menu to perform similar operations.</para> + +<variablelist> + +<varlistentry id="menu-view-whatsnext"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_view_whatsnext.png" + format="PNG"/></imageobject></inlinemediaobject> +View</guimenu><guimenuitem>What's Next</guimenuitem></menuchoice></term> +<listitem><para><action>Switch the display to the what's next view.</action></para> +<para>This view displays your next events and to-dos. Events and to-dos are +displayed one per line.</para> +<para>For more information about this action, please refer to +<xref linkend="whatsnext-view" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-view-day"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_view_day.png" + format="PNG"/></imageobject></inlinemediaobject> +View</guimenu><guimenuitem>Day</guimenuitem></menuchoice></term> +<listitem><para><action>Switch the display to the day view.</action></para> +<para>For more information about this action, please refer to +<xref linkend="agenda-view" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-view-xdays"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_view_xdays.png" + format="PNG"/></imageobject></inlinemediaobject> +View</guimenu><guimenuitem>Next x Days</guimenuitem></menuchoice></term> +<listitem><para><action>Switch the display to the next x day view, where x is +defined in &korganizer; main configurations.</action></para> +<para>For more information about this action, please refer to +<xref linkend="agenda-view" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-view-workweek"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata + fileref="i_view_work_week.png" +format="PNG"/></imageobject></inlinemediaobject> View</guimenu><guimenuitem>Work +Week</guimenuitem></menuchoice></term> +<listitem><para><action>Switch the display to the work week +view.</action></para> +<para>This is the same as the week view, except only the working days of the +week are shown.</para> +<para>For more information about this action, please refer to +<xref linkend="agenda-view" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-view-week"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_view_week.png" + format="PNG"/></imageobject></inlinemediaobject> +View</guimenu> <guimenuitem>Week</guimenuitem></menuchoice></term> +<listitem><para><action>Switch the display to the week view.</action></para> +<para>The week view provides a view similar to the day view. Events for seven +days are shown next to each other. All of the functions available for the day +view are available in the week view, too.</para> +<para>For more information about this action, please refer to +<xref linkend="agenda-view" />.</para></listitem> +</varlistentry> + +<varlistentry id="menu-view-month"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_view_month.png" + format="PNG"/></imageobject></inlinemediaobject> View</guimenu> +<guimenuitem>Month</guimenuitem> +</menuchoice></term> +<listitem><para><action>Switch the display to the Month view.</action></para> +<para>For more information about this action, please refer to +<xref linkend="agenda-view" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-view-list"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_view_list.png" + format="PNG"/></imageobject></inlinemediaobject> +View</guimenu><guimenuitem>List</guimenuitem></menuchoice></term> +<listitem><para><action>Switch the display to the list view.</action></para> +<para>For more information about this action, please refer to +<xref linkend="list-view" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-view-todo"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata + fileref="i_view_todo_list.png" +format="PNG"/></imageobject></inlinemediaobject> View</guimenu> + <guimenuitem>To-do List</guimenuitem></menuchoice></term> +<listitem><para><action>Switch the display to the to-do list view.</action></para> +<para>For more information about this action, please refer to +<xref linkend="todo-view" />.</para> +</listitem> +</varlistentry> + +<varlistentry id="menu-view-journal"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata + fileref="i_view_journal.png" +format="PNG"/></imageobject></inlinemediaobject>View</guimenu> +<guimenuitem>Journal</guimenuitem> +</menuchoice></term> +<listitem><para><action>Switch the display to the journal view.</action></para> +<para>For more information about this action, please refer to +<xref linkend="journal-view" />.</para></listitem> +</varlistentry> + +<varlistentry id="menu-view-update"> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Refresh</guimenuitem> +</menuchoice></term> +<listitem><para> +<action>Updates or refreshes the currently displayed view.</action> +</para></listitem> +</varlistentry> + +<varlistentry id="menu-view-zoom"> +<term><menuchoice> +<guimenu>View</guimenu><guisubmenu>Zoom</guisubmenu></menuchoice></term> +<listitem><para><action>Use this submenu to adjust the current view to show +more or less data.</action></para> +<para>In the agenda view (day(s) or week view), you can use the zoom actions to +show more or less days (<guimenuitem>Zoom In Horizontally</guimenuitem> and +<guimenuitem>Zoom Out Horizontally</guimenuitem>), or more or less hours in the +day (<guimenuitem>Zoom In Vertically</guimenuitem> and +<guimenuitem>Zoom Out Vertically</guimenuitem>).</para></listitem> +</varlistentry> + +<varlistentry id="menu-view-filter"> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Filter</guisubmenu> +</menuchoice></term> +<listitem><para>This submenu offers access to the filters already created using +the <link linkend="menu-settings-edit-filters"><guilabel>Edit +Filters</guilabel></link> dialog. <action>Select on this submenu the filter +that will be used in &korganizer; view.</action>. If you don't want to use a +filter, choose <guilabel>No filter</guilabel>.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="reference-menus-go"> +<title><guimenu>Go</guimenu></title> + +<para>For more information about browsing &korganizer; views, please refer to +<xref linkend="description-view" />.</para> + +<variablelist> +<varlistentry id="menu-go-previous-day"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_go_backward.png" +format="PNG"/></imageobject></inlinemediaobject> +Go</guimenu><guimenuitem>Go Backward</guimenuitem></menuchoice></term> +<listitem><para><action>Go to the previous day, week or month, depending on +the view.</action></para></listitem> +</varlistentry> +<varlistentry id="menu-go-next-day"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_go_forward.png" + format="PNG"/></imageobject></inlinemediaobject> +Go</guimenu><guimenuitem>Go Forward</guimenuitem></menuchoice></term> +<listitem><para><action>Go to the next day, week, or month, depending on the +view.</action></para></listitem> +</varlistentry> +<varlistentry id="menu-go-goto-today"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_go_to_today.png" +format="PNG"/></imageobject></inlinemediaobject> +Go</guimenu><guimenuitem>Go to Today</guimenuitem></menuchoice></term> +<listitem><para><action>Go to the period of time that includes the current day.</action></para></listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="reference-menus-actions"> +<title><guimenu>Actions</guimenu></title> + +<variablelist> +<varlistentry id="menu-actions-new-event"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_actions_newevent.png" +format="PNG"/></imageobject></inlinemediaobject>Actions</guimenu> +<guimenuitem>New Event...</guimenuitem> +</menuchoice></term> +<listitem><para>Choose <guilabel>New Event...</guilabel> to <action>create a +new event</action>.</para> +<para>You can get a detailed description of the event window in <link +linkend="entering-data-events">the Entering Events</link> section.</para></listitem> +</varlistentry> + +<varlistentry id="menu-actions-new-todo"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata fileref="i_actions_newtodo.png" +format="PNG"/></imageobject></inlinemediaobject>Actions</guimenu> +<guimenuitem>New To-do...</guimenuitem> +</menuchoice></term> +<listitem><para>Choose <guilabel>New To-do...</guilabel> to <action>create a +new to-do</action>. Initially the to-do has no due date, but you can specify +one.</para> +<para>You can get a detailed description of the to-do window in <link +linkend="entering-data-to-do">the Entering To-dos</link> section.</para></listitem> +</varlistentry> + +<varlistentry id="menu-actions-new-subtodo"> +<term><menuchoice> +<guimenu>Actions</guimenu> +<guimenuitem>New Sub-to-do...</guimenuitem> +</menuchoice></term> +<listitem><para>Choose <guilabel>New Sub-to-do...</guilabel> to <action>start +writing a new sub-to-do. The currently selected to-do will be the the +sub-to-do parent.</action>. Initially the to-do has no due date, but you can +specify one.</para> +<para>You can get a detailed description of the to-do window in <link +linkend="entering-data-to-do">Entering To-dos</link> section.</para></listitem> +</varlistentry> + +<varlistentry id="menu-actions-new-journal"> +<term><menuchoice> +<guimenu>Actions</guimenu> +<guimenuitem>New Journal...</guimenuitem> +</menuchoice></term> +<listitem><para>Choose <guilabel>New Journal...</guilabel> to <action>start +writing a new journal entry.</action>.</para></listitem> +</varlistentry> + +<varlistentry id="menu-actions-show-event"> +<term><menuchoice> +<guimenu>Actions</guimenu> +<guimenuitem>Show</guimenuitem> +</menuchoice></term> +<listitem><para>Choose <guilabel>Show</guilabel> to <action>open a dialog +showing the details of the currently selected journal entry, event or +to-do.</action></para></listitem> +</varlistentry> + +<varlistentry id="menu-actions-edit-event"> +<term><menuchoice> +<guimenu>Actions</guimenu> +<guimenuitem>Edit...</guimenuitem> +</menuchoice></term> +<listitem><para>Choose <guilabel>Edit...</guilabel> to <action>edit the +currently selected journal entry, event or to-do.</action></para></listitem> +</varlistentry> + +<varlistentry id="menu-actions-delete-event"> +<term><menuchoice> +<guimenu>Actions</guimenu> +<guimenuitem>Delete</guimenuitem> +</menuchoice></term> +<listitem><para>Choose <guilabel>Delete</guilabel> to <action>remove the +currently selected journal entry, event or to-do.</action></para></listitem> +</varlistentry> + +<varlistentry id="menu-actions-make-subtodo-independent"> +<term><menuchoice> +<guimenu>Actions</guimenu> +<guimenuitem>Make Sub-to-do Independent</guimenuitem> +</menuchoice></term> +<listitem><para>Choose <guilabel>Make Sub-to-do Independent</guilabel> to +detach the currently selected sub-to-do item from its parent and make it an +independent to-do item.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="reference-menus-schedule"> +<title><guimenu>Schedule</guimenu></title> + +<variablelist> + +<varlistentry id="menu-schedule-publish"> +<term><menuchoice> +<guimenu>Schedule</guimenu> +<guimenuitem>Publish Item Information...</guimenuitem> +</menuchoice></term> +<listitem><para>Email the selected event, to-do or journal entry in the +iCalendar format.</para> +<para>For more information about this action, please refer to +<xref linkend="publish" />.</para></listitem> +</varlistentry> + +<varlistentry id="menu-schedule-request"> +<term><menuchoice> +<guimenu>Schedule</guimenu> +<guimenuitem>Send Invitation to Attendees</guimenuitem> +</menuchoice></term> +<listitem><para>Send the selected to-do or event to the attendees, and, +if necessary, request a response from them.</para> +<para>For more information about this action, please refer to +<xref linkend="request" />.</para></listitem> +</varlistentry> + +<varlistentry id="menu-schedule-reply"> +<term><menuchoice> +<guimenu>Schedule</guimenu> +<guimenuitem>Send Status Update</guimenuitem> +</menuchoice></term> +<listitem><para>If you changed your status as an attendee, choose this +menu item to send your updated status (accepted, tentative, &etc;) to the item's +organizer.</para> +<para>For more information about this action, please refer to +<xref linkend="reply" />.</para></listitem> +</varlistentry> + +<varlistentry id="menu-schedule-cancel"> +<term><menuchoice> +<guimenu>Schedule</guimenu> +<guimenuitem>Send Cancellation to Attendees</guimenuitem> +</menuchoice></term> +<listitem><para>If you plan to cancel an event or to-do, select it, and +choose this menu item to notify the attendees about the cancellation.</para> +<para>For more information about this action, please refer to +<xref linkend="cancel" />.</para></listitem> +</varlistentry> + +<varlistentry id="menu-schedule-refresh"> +<term><menuchoice> +<guimenu>Schedule</guimenu> +<guimenuitem>Request Update</guimenuitem> +</menuchoice></term> +<listitem><para>Request the latest version of the selected event or to-do from +the organizer.</para> +<para>For more information about this action, please refer to +<xref linkend="refresh" />.</para></listitem> +</varlistentry> + +<varlistentry id="menu-schedule-counter"> +<term><menuchoice> +<guimenu>Schedule</guimenu> +<guimenuitem>Request Change</guimenuitem> +</menuchoice></term> +<listitem><para>Send an alternative proposal to the organizer of the selected +event or to-do. +</para> +<para>For more information about this action, please refer to +<xref linkend="counter" />.</para></listitem> +</varlistentry> + +<varlistentry id="menu-schedule-mail-freebusy"> +<term><menuchoice> +<guimenu>Schedule</guimenu> +<guimenuitem>Mail Free Busy Information...</guimenuitem> +</menuchoice></term> +<listitem><para>Email your Free Busy information to one or more +email addresses.</para> +<para>For more information about this action, please refer to +<xref linkend="free-busy" />.</para></listitem> +</varlistentry> + +<varlistentry id="menu-schedule-upload-freebusy"> +<term><menuchoice> +<guimenu>Schedule</guimenu> +<guimenuitem>Upload Free Busy Information</guimenuitem> +</menuchoice></term> +<listitem><para>Upload your Free Busy information to the groupware server. +Other users will then be able to retrieve the information.</para> +<para>For more information about this action, please refer to +<xref linkend="free-busy" />.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="reference-menus-settings"> +<title><guimenu>Settings</guimenu></title> + +<variablelist> +<varlistentry id="menu-settings-show-toolbar"> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guisubmenu>Toolbars</guisubmenu> +</menuchoice></term> +<listitem><para><action>Click the menu items of this submenu to show or hide +&korganizer; toolbars.</action></para></listitem> +</varlistentry> + +<varlistentry id="menu-settings-show-statusbar"> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Show Status bar</guimenuitem> +</menuchoice> or <menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Hide Status bar</guimenuitem> +</menuchoice></term> +<listitem><para><action>Choose this menu item to toggle the display of the +status bar on and off</action>.</para></listitem> +</varlistentry> + +<varlistentry id="menu-settings-sidebar"> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guisubmenu>Sidebar</guisubmenu> +</menuchoice></term> +<listitem><para><action>Click the menu items of this submenu to show or hide +&korganizer; sidebar components</action>. Note that the sidebar is visible only +when <link linkend="config-main-views">the current view does not use the full +window.</link></para></listitem> +</varlistentry> + +<varlistentry id="menu-settings-show-resource-buttons"> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guisubmenu>Sidebar</guisubmenu> +<guimenuitem>Show Resource Buttons</guimenuitem> +</menuchoice></term> +<listitem><para><action>Click this menu item toggle the display of the +<link linkend="managing-resources">resource view sidebar</link> buttons on and +off</action>.</para></listitem> +</varlistentry> + +<varlistentry id="menu-settings-configure-date-time"> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Date & Time...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Click this menu item to set the desktop date and time +formats</action>. Note that this setting is shared between other desktop +applications.</para></listitem> +</varlistentry> + +<varlistentry id="menu-settings-edit-filters"> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guisubmenu>Manage View Filters...</guisubmenu> +</menuchoice></term> +<listitem><para><action>Choose this menu item to open the <guilabel>Edit +Filters</guilabel> dialog</action>. Using this dialog, you can create, delete +and edit filters that will affect which items will be displayed by +&korganizer;.</para></listitem> +</varlistentry> + +<varlistentry id="menu-settings-edit-categories"> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Manage Categories...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Choose this menu item to open the <guilabel>Edit +Categories</guilabel> dialog</action>. Using this dialog, you can create, delete +and edit calendar item categories. Categories are used to organize your events and +to-dos in related groups.</para></listitem> +</varlistentry> + +<varlistentry id="menu-settings-configure-shortcuts"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata + fileref="i_settings_prefs.png" +format="PNG"/></imageobject></inlinemediaobject> +Settings</guimenu> +<guimenuitem>Configure Shortcuts...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Choose this menu item to open the <guilabel>Configure +Shortcuts</guilabel> dialog</action>. This dialog allows you to assign shortcuts +to &korganizer; actions, and configure the shortcuts already assigned.</para></listitem> +</varlistentry> + +<varlistentry id="menu-settings-configure-toolbars"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata + fileref="i_settings_prefs.png" +format="PNG"/></imageobject></inlinemediaobject> +Settings</guimenu> +<guimenuitem>Configure Toolbars...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Choose this menu item to open the <link +linkend="config-toolbars"><guilabel>Configure +Toolbars</guilabel> dialog</link></action>. This dialog allows you to add, remove and +change the order of the actions in &korganizer; toolbars.</para></listitem> +</varlistentry> + +<varlistentry id="menu-settings-configure-korganizer"> +<term><menuchoice> +<guimenu><inlinemediaobject><imageobject><imagedata + fileref="i_settings_prefs.png" +format="PNG"/></imageobject></inlinemediaobject> +Settings</guimenu><guimenuitem>Configure &korganizer;...</guimenuitem></menuchoice></term> +<listitem><para>Choose the <menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Configure &korganizer;...</guimenuitem> </menuchoice> menu item + to display &korganizer; <link linkend="config-main">Configure +dialog</link>.</para> +<para>For more information about this action, please refer to +<xref linkend="config-main" />.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="reference-menus-help"> +<title><guimenu>Help</guimenu></title> + +&help.menu.documentation; + +</sect2> + +</sect1> + +<sect1 id="reference-hotkey"> +<title>HotKeys</title> + +<para>This is a reference to all hotkeys and their corresponding description in +the handbook.</para> + + +<sect2 id="reference-hotkey-sortalpha"> +<title>Hotkeys Sorted Alphabetically</title> + +<informaltable> +<tgroup cols="2"> +<colspec colname="hotkey"/> +<colspec colname="desc"/> +<thead> +<row> + <entry>Hotkey</entry> + <entry>Description</entry> +</row> +</thead> +<tbody> +<row> + <entry><keycombo action="simul">&Ctrl; <keycap>C</keycap> </keycombo></entry> + <entry><link linkend="menu-edit-copy"><menuchoice><guimenu>Edit</guimenu> + <guimenuitem>Copy</guimenuitem></menuchoice></link> equivalent; copy the + selection to clipboard.</entry> +</row> +<row> + <entry><keycombo action="simul">&Ctrl; <keycap>F</keycap></keycombo></entry> + <entry><link linkend="menu-edit-find"><menuchoice><guimenu>Edit</guimenu> + <guimenuitem>Find</guimenuitem></menuchoice></link> equivalent; Find data in + current calendar.</entry> +</row> +<row> + <entry><keycap>F1</keycap></entry> + <entry><menuchoice><guimenu>Help</guimenu> + <guimenuitem>Contents</guimenuitem></menuchoice> equivalent; help for + &korganizer;.</entry> +</row> +<row> + <entry><keycombo action="simul">&Ctrl; <keycap>N</keycap></keycombo></entry> + <entry><link linkend="menu-file-new"><menuchoice><guimenu>File</guimenu> + <guimenuitem>New</guimenuitem></menuchoice></link> equivalent; create and open + new calendar.</entry> +</row> +<row> + <entry><keycombo action="simul">&Ctrl; <keycap>O</keycap></keycombo></entry> + <entry><link linkend="menu-file-open"><menuchoice><guimenu>File</guimenu> + <guimenuitem>Open</guimenuitem></menuchoice></link> equivalent; open a + calendar file in the current window.</entry> +</row> +<row> + <entry><keycombo action="simul">&Ctrl; <keycap>P</keycap></keycombo></entry> + <entry><link linkend="menu-file-print"><menuchoice><guimenu>File</guimenu> + <guimenuitem>Print</guimenuitem></menuchoice></link> equivalent; print current + calendar.</entry> +</row> +<row> + <entry><keycombo action="simul">&Ctrl; <keycap>Q</keycap></keycombo></entry> + <entry><link linkend="menu-file-quit"><menuchoice><guimenu>File</guimenu> + <guimenuitem>Quit</guimenuitem></menuchoice></link> equivalent; quit current + calendar. </entry> +</row> +<row> + <entry><keycombo action="simul">&Ctrl; <keycap>S</keycap></keycombo></entry> + <entry><link linkend="menu-file-save"><menuchoice><guimenu>File</guimenu> + <guimenuitem>Save</guimenuitem></menuchoice></link> equivalent; save current + calendar.</entry> +</row> +<row> + <entry><keycombo action="simul">&Ctrl; <keycap>V</keycap></keycombo></entry> + <entry><link linkend="menu-edit-paste"><menuchoice><guimenu>Edit</guimenu> + <guimenuitem>Paste</guimenuitem></menuchoice></link> equivalent; paste data + from clipboard.</entry> +</row> +<!--<row> + <entry><keycombo action="simul">&Ctrl; <keycap>W</keycap></keycombo></entry> + <entry><link linkend="menu-file-close"><menuchoice><guimenu>File</guimenu> + <guimenuitem>Close</guimenuitem></menuchoice></link> equivalent; close current + calendar.</entry> +</row>--> +<row> + <entry><keycombo action="simul">&Ctrl; <keycap>X</keycap></keycombo></entry> + <entry><link linkend="menu-edit-cut"><menuchoice><guimenu>Edit</guimenu> + <guimenuitem>Cut</guimenuitem></menuchoice></link> equivalent; cut the + selection to the clipboard.</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +</sect2> + +<sect2 id="reference-hotkey-sortbyfunc"> +<title>Hotkeys Sorted by Function</title> + +<informaltable> +<tgroup cols="2"> +<colspec colname="desc"/> +<colspec colname="hotkey"/> +<thead> +<row> + <entry>Description</entry> + <entry>Hotkey</entry> +</row> +</thead> +<tbody> +<!--<row> + <entry><emphasis>Close:</emphasis> <link linkend="menu-file-close"> <menuchoice> + <guimenu>File</guimenu> <guimenuitem>Close</guimenuitem></menuchoice></link> + equivalent; close current calendar.</entry> + <entry><keycombo action="simul">&Ctrl; <keycap>W</keycap></keycombo></entry> +</row>--> +<row> + <entry><emphasis>Copy:</emphasis> <link linkend="menu-edit-copy"> <menuchoice> + <guimenu>Edit</guimenu> <guimenuitem>Copy</guimenuitem></menuchoice> </link> + equivalent; copy the selection to clipboard.</entry> + <entry><keycombo action="simul">&Ctrl; <keycap>C</keycap></keycombo></entry> +</row> +<row> + <entry><emphasis>Cut:</emphasis> <link linkend="menu-edit-cut"> <menuchoice> + <guimenu>Edit</guimenu> <guimenuitem>Cut</guimenuitem></menuchoice> </link> + equivalent; cut the selection to the clipboard.</entry> + <entry><keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo></entry> +</row> +<row> + <entry><emphasis>Find:</emphasis> <link linkend="menu-edit-find"> <menuchoice> + <guimenu>Edit</guimenu> <guimenuitem>Find</guimenuitem></menuchoice></link> + equivalent; Find data in current calendar.</entry> + <entry><keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo></entry> +</row> +<row> + <entry><emphasis>Help:</emphasis> <menuchoice> + <guimenu>Help</guimenu> + <guimenuitem>Contents</guimenuitem></menuchoice> equivalent; help for + &korganizer;.</entry> + <entry><keycap>F1</keycap></entry> +</row> +<row> + <entry><emphasis>New:</emphasis> <link linkend="menu-file-new"> <menuchoice> + <guimenu>File</guimenu> <guimenuitem>New</guimenuitem></menuchoice></link> + equivalent; create and open new calendar.</entry> + <entry><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></entry> +</row> +<row> + <entry><emphasis>Open:</emphasis> <link linkend="menu-file-open"> <menuchoice> + <guimenu>File</guimenu> <guimenuitem>Open</guimenuitem></menuchoice></link> + equivalent; open a calendar file in the current window.</entry> + <entry><keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo></entry> +</row> +<row> + <entry><emphasis>Paste:</emphasis> <link linkend="menu-edit-paste"> <menuchoice> + <guimenu>Edit</guimenu> <guimenuitem>Paste</guimenuitem></menuchoice></link> + equivalent; paste data from clipboard.</entry> + <entry><keycombo action="simul">&Ctrl;<keycap>V</keycap></keycombo></entry> +</row> +<row> + <entry><emphasis>Print:</emphasis> <link linkend="menu-file-print"> <menuchoice> + <guimenu>File</guimenu> <guimenuitem>Print</guimenuitem> </menuchoice> </link> + equivalent; print current calendar.</entry> + <entry><keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo></entry> +</row> +<row> + <entry><emphasis>Quit:</emphasis> <link linkend="menu-file-quit"> <menuchoice> + <guimenu>File</guimenu> <guimenuitem>Quit</guimenuitem></menuchoice></link> + equivalent; quit current calendar. </entry> + <entry><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></entry> +</row> +<row> + <entry><emphasis>Save:</emphasis> <link linkend="menu-file-save"> <menuchoice> + <guimenu>File</guimenu> <guimenuitem>Save</guimenuitem></menuchoice></link> + equivalent; save current calendar.</entry> + <entry><keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo></entry> +</row> +</tbody> +</tgroup> +</informaltable> + +</sect2> + +</sect1> + +<sect1 id="reference-action-buttons"> +<title>Action Buttons</title> + +<para>Many windows contain buttons <guibutton>Default</guibutton>, +<guibutton>Delete</guibutton>, <guibutton>OK</guibutton>, +<guibutton>Apply</guibutton>, and <guibutton>Cancel</guibutton>. With these +buttons you will decide whether the data that you entered into the window will +be saved or forgotten.</para> + +<variablelist> +<varlistentry> +<term><guibutton>Default</guibutton></term> +<listitem><para>If you click the <guibutton>Default</guibutton> button, changes +you have made will be forgotten, and all choices will be returned to their +default values.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Delete</guibutton></term> +<listitem><para>Click <guibutton>Delete</guibutton> to completely remove the +event or event that you are editing from the calendar.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>OK</guibutton></term> +<listitem><para>When you click the <guibutton>OK</guibutton> button, your +changes will be remembered and &korganizer; will close the + window.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Apply</guibutton></term> +<listitem><para>When you click the <guibutton>Apply</guibutton> button, your +changes will be remembered, and the window will remain on screen for further +editing.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Cancel</guibutton></term> +<listitem><para>If you click the <guibutton>Cancel</guibutton> button, your +editing will be forgotten, and &korganizer; will close the + window.</para></listitem> +</varlistentry> +</variablelist> + +</sect1> + +</chapter> + +<chapter id="other-features"> +<title>Other Features</title> + +<para>In this chapter, you'll learn other useful features of +&korganizer;: what tricks you can do with a click +of your mouse and what interaction between &korganizer; and &konqueror; is +possible.</para> + +<para>You'll also learn about synchronizing with your &PalmPilot; or +compatible handheld +computer.</para> + +<sect1 id="other-features-commandline-options"> +<title>Command Line</title> + +<para>A nice program to access a &kde; calendar from the command line is konsolekalendar, which +is included in the kdepim package together with &korganizer;.</para> + +</sect1> + +<sect1 id="other-features-drag-and-drop"> +<title>Drag and Drop Operations</title> + +<para>&korganizer; can be easily controlled with your mouse. The supported + drag-and-drop +operations are detailed below.</para> + +<itemizedlist> +<listitem><para>Any event can be re-sized with your mouse. Simply move the mouse +pointer near the top or bottom edge of the event, and drag the edge up or +down. This way you can visually modify the starting and ending time of your +appointment. This works in the Day, Week and Work Week views.</para></listitem> +<listitem><para>Any event can be rescheduled with your mouse. Move the mouse +pointer over the event, and drag it to a new time location. This works in the +Day, Week and Work Week views.</para></listitem> +<listitem><para>Events can be copied to other, presently non-visible dates. Move +the mouse pointer over the event, and drag it to the Date Navigator on the left +side of the current calendar, or to the Date Navigator of a different +calendar.</para> +<tip><para>However, you cannot drag from agenda view in one calendar to +agenda view in other calendar.</para></tip></listitem> +<listitem><para>Toolbars can be dragged on the screen. Move the mouse pointer +over the tollbar's handle, and drag it to a new location on your +screen.</para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="other-features-konqueror-interaction"> +<title>&konqueror; Interaction</title> + +<para>&konqueror; recognizes the vCalendar format used by +&korganizer;. If you use &konqueror; to navigate to your calendar, it +will be displayed <emphasis>inside</emphasis> &konqueror; as a live +object. You will be able to perform most operations with your calendar +inside &konqueror;; you will not need to start &korganizer;. In +technical jargon, this is described as <quote>embedding vCalendar as +KPart inside &konqueror;</quote>.</para> + +</sect1> + +<sect1 id="other-features-palm-sync"> +<title>Palm Synchronization</title> + +<para>Palm Synchronization can be done via &kpilot;. Choose +<menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure &kpilot;</guimenuitem> +</menuchoice> and check the <guilabel>Calendar (&korganizer;)</guilabel> and +<guilabel>To-do's (&korganizer;)</guilabel> boxes. After synchronization the +Calendar and To-do's should be visible in &korganizer;.</para> +<para>See the <link linkend="faq">&FAQ;</link> for one of the most common &PalmPilot; +syncing problems.</para> + +</sect1> + +</chapter> + +<chapter id="faq"> +<title>Questions and Answers</title> + +<qandaset id="faq-questions"> +<qandaentry> +<question> +<para>Can I import my old <application>Ical</application> data?</para> +</question> +<answer><para>Sure! Follow the instructions in <link +linkend="menu-file-import-ical">Import From &UNIX; Ical section</link>.</para> +</answer> +</qandaentry> +<qandaentry> +<question> +<para>Can I import data from &Microsoft; +<application>Outlook</application>?</para> +</question> +<answer><para>Yes you can, but you must first tell +<application>Outlook</application> to export its data to vCalendar format. Then +you must copy this data to your home folder, click +<menuchoice><guimenu>File</guimenu> <guimenuitem>Open</guimenuitem> +</menuchoice>, navigate to the file and double-click it. +For more information on importing data from &Microsoft; +<application>Outlook</application>, please check +<xref linkend="outlook-to-vcalendar-ws" />.</para> +</answer> +</qandaentry> + +<qandaentry> +<question><para>I'm trying to sync &korganizer; with my &PalmPilot;, +but nothing happens. What else do I need to do?</para> +</question> +<answer><para> +<itemizedlist> +<listitem><para>Make sure no form of &korganizer; is running: neither +&korganizer; itself nor the alarm daemon in the system tray. +</para> +</listitem> +<listitem><para>Make sure the versions of the &kpilot; datebook conduit and +&korganizer; are compatible.</para> +</listitem> +</itemizedlist> +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Can I use freebusy-time with &korganizer;?</para> +</question> +<answer><para>yes, follow the instructions in <link +linkend="config-main-free-busy">Free/Busy</link>.</para> +</answer> +</qandaentry> +</qandaset> + +</chapter> + +&outlook-to-vcalendar-workshop; + +<chapter id="credits"> +<title>Credits and License</title> + +<para>&korganizer;</para> + +<para>Program copyright 2000-2004, The &kde; Developers</para> + +<para>&korganizer; homepage is at <ulink +url="http://korganizer.kde.org">http://korganizer.kde.org</ulink></para> + +<para>If you discover bugs or see room for improvement in &korganizer; please +visit <ulink url="http://korganizer.kde.org/contact/bugswishes.html"> +http://korganizer.kde.org/contact/bugswishes.html</ulink>.</para> + +<para>Contributors:</para> + +<itemizedlist> +<listitem><para>Reinhold Kainhofer <email>reinhold@kainhofer.com</email></para> +</listitem> +<listitem><para>&Cornelius.Schumacher; &Cornelius.Schumacher.mail;</para> +</listitem> +<listitem><para>&Preston.Brown; &Preston.Brown.mail;</para> +</listitem> +</itemizedlist> + +<para>Documentation copyright 2000 &Milos.Prudek;</para> +<para>Documentation copyright 2001 Paul E. Ahlquist, Jr +<email>&Paul.E.Ahlquist.Jr.mail;</email></para> +<para>Documentation copyright 2004 Jürgen Nagel +<email>juergen.nagel@student.fh-reutlingen.de</email></para> +<para>Documentation copyright 2005 Carlos Leonhard Woelz +<email>carloswoelz@imap-mail.com</email></para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> +&underFDL; + +&underGPL; + +</chapter> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-korg"> +<title>How to Obtain &korganizer;</title> + +&install.intro.documentation; + +<para>Click the <guisubmenu>Applications</guisubmenu> menu of the +<guimenu>main</guimenu> menu to see if &korganizer; is already installed on your +system. If &korganizer; is not there, either it is not installed, or perhaps + the +administrator of your system has moved it to some other place.</para> + +<para>&korganizer; homepage is at <ulink +url="http://korganizer.kde.org">http://korganizer.kde.org</ulink> +</para> + +</sect1> + +<sect1 id="requirements"> +<title>Requirements</title> + +<para>&korganizer; requires &kde; 3.4. It requires roughly 2MB of space +in your &kde; system folder. Your calendars will require additional +space in your home folder. Very large calendars slow down +&korganizer; operation, therefore periodic cleanup is advisable.</para> + +<para>&korganizer; needs about 5 Megabytes of memory to run, but this may vary + depending +on your platform and the size of your calendar(s).</para> + +<para>All required libraries are part of standard &kde; libraries +(kdelibs). &kde; base package (kdebase) must also be installed to change +localization preferences like date and time formats. &korganizer; itself +is in the kdepim package. All packages can be found on <ulink +url="http://www.kde.org">&kde; home page.</ulink>.</para> + +<para>The &korganizer; homepage is at <ulink +url="http://korganizer.kde.org">http://korganizer.kde.org</ulink> +</para> + +</sect1> + +</appendix> + +<glossary id="glossary"> +<title>Glossary</title> + +<glossentry id="gloss-calendar-widget"> +<glossterm>Calendar Widget</glossterm> +<glossdef> + +<para>A tool for choosing the date inside certain entry windows, like event +editing window. It is displayed as a small button to the right of the date +field. When you click the button, you will see a month calendar. Use the arrows +to go to a desired date, or click the month name or year number to go +directly to the desired month or year.</para> + +</glossdef> +</glossentry> + +<glossentry id="gloss-date-navigator"> +<glossterm>Date Navigator</glossterm> +<glossdef> + +<para>The calendar that is in the upper-left corner of the &korganizer; window. +It is the main way provided to navigate among dates, and to select from them. +The single-arrow icons move forwards and backwards in time by increments of a +month, while the double-arrows allow moving by years at a time. Today's date +will be outlined with a small box. Dates which have events scheduled on them +will be bold. If you want to select a date, simply click it. Hold down the +Control key and click the dates if you wish to select multiple neighbor dates at +once. The dates will be displayed in the main panel.</para> + +<para>Recurring events are not always displayed. You can forbid the display of +recurring appointments in the Date Navigator. Get more information in the <link +linkend="config-main-views">Views chapter</link>.</para> + +</glossdef> +</glossentry> + +<glossentry id="gloss-due-date"> +<glossterm>Due Date</glossterm> +<glossdef> + +<para>A due date is simply the date when your to-do must be finished. For +instance, if your to-do is that you must return your books to the library +by 16th November, that date is called <quote>the to-do due +date</quote></para> + +</glossdef> +</glossentry> + +<!--<glossentry id="gloss-group-scheduling"> +<glossterm>Group scheduling features</glossterm> +<glossdef> + +<para>These features are planned for the future versions of &korganizer;. Group +scheduling will facilitate member roles (attendee, owner, organizer), time +conflict resolution, event reminder distribution, response collection and +evaluation. In other words, you will be able to appoint attendees, invite them +automatically, and see who accepted or refused attending the appointment.</para> + +<para>Currently, group scheduling features are not working. However, hooks exist +in the calendar data structures for these features. <guilabel>Private</guilabel> +check box, <guilabel>Require response</guilabel> check box and +<guilabel>E-mail</guilabel> field will then be fully employed. These controls +are described in more detail in <link linkend="entering-data">Entering +Data</link> chapter, in the <link +linkend="entering-data-events-attendees">Attendees section</link> of Windows +reference, and in the <link linkend="config-main-personal">Personal +Preferences</link> section.</para> + +</glossdef> +</glossentry> +--> +<glossentry id="gloss-main-panel"> +<glossterm>Main panel</glossterm> +<glossdef> +<para>Normally the largest part of the screen, to the right of the Date +Navigator. It displays the View of the day, workdays, week or month, the List +View or the to-do list view.</para> +<para>The right mouse button can be used in the List view and to-do list view +only. It displays a local menu. The left mouse button can be used in any +view.</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-freebusy"> +<glossterm>Free/busy</glossterm> +<glossdef> +<para>The free/busy information is a set of busy time intervals. By presenting +the intervals when one already has previous commitments, others can avoid +arranging appointments for these periods. Note that only the times are published, +not the event titles, descriptions or attendees. In other words, the +free/busy information is the availability schedule.</para> +<para>When adding attendees to your event, you need to know if they are +busy or free in that particular time before sending the invitations. +If the attendees make their free/busy information available, &korganizer; +can retrieve this information and display it in the +<guilabel>Free/Busy</guilabel> tab of the <guilabel>Edit Event</guilabel> +dialog.</para> +</glossdef> +</glossentry> + +<!--FIXME: remove this or transform in glossary items + +<sect1 id="course-event-types"> +<title>Calendar Item Types</title> + +<para>There are three types of items:</para> + +<itemizedlist> +<listitem><para>Events start and finish at distinct date. You can also specify +distinct start and finish times, but you don't have to. While business +meetings, personal anniversaries and cinema visits are examples of carefully +planned events with exact time scheduling, a holiday is an event that takes +several days and thus there is no need to specify exact start and finish +times.</para></listitem> + +<listitem><para>To-do's must take place no later than a +certain date, but they can also take place sooner.</para></listitem> +</itemizedlist> + +<para>Naturally, what began as a To-do may later require exact timing. +Say it is July 1 and you need to go to a hairdresser within a week. +On July 3 you talk to your hairdresser and agree on an exact time. Thus the +original To-do becomes similar to an appointment. </para> + +<para>&korganizer; makes adding exact time to a To-do very easy. If you +check the <guilabel>Due</guilabel> check box and/or the <guilabel>Start</guilabel> +check box you can specify the appropriate dates, when you check the +<guilabel>Time associated</guilabel> check box and fill in the associated times, your +To-do becomes very similar to an event.</para> + +</sect1> + +--> + +</glossary> + +&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/korganizer/korganizer-resource.png b/doc/korganizer/korganizer-resource.png Binary files differnew file mode 100644 index 000000000..09b682d79 --- /dev/null +++ b/doc/korganizer/korganizer-resource.png diff --git a/doc/korganizer/o2v_importing1.png b/doc/korganizer/o2v_importing1.png Binary files differnew file mode 100644 index 000000000..6d4402add --- /dev/null +++ b/doc/korganizer/o2v_importing1.png diff --git a/doc/korganizer/o2v_importing2.png b/doc/korganizer/o2v_importing2.png Binary files differnew file mode 100644 index 000000000..19bfba2f5 --- /dev/null +++ b/doc/korganizer/o2v_importing2.png diff --git a/doc/korganizer/o2v_importing3.png b/doc/korganizer/o2v_importing3.png Binary files differnew file mode 100644 index 000000000..efc085056 --- /dev/null +++ b/doc/korganizer/o2v_importing3.png diff --git a/doc/korganizer/o2v_main.png b/doc/korganizer/o2v_main.png Binary files differnew file mode 100644 index 000000000..3f9e47acb --- /dev/null +++ b/doc/korganizer/o2v_main.png diff --git a/doc/korganizer/o2v_progress.png b/doc/korganizer/o2v_progress.png Binary files differnew file mode 100644 index 000000000..50662af38 --- /dev/null +++ b/doc/korganizer/o2v_progress.png diff --git a/doc/korganizer/o2v_save.png b/doc/korganizer/o2v_save.png Binary files differnew file mode 100644 index 000000000..ba3109154 --- /dev/null +++ b/doc/korganizer/o2v_save.png diff --git a/doc/korganizer/o2v_warning.png b/doc/korganizer/o2v_warning.png Binary files differnew file mode 100644 index 000000000..83208e14b --- /dev/null +++ b/doc/korganizer/o2v_warning.png diff --git a/doc/korganizer/organizer.png b/doc/korganizer/organizer.png Binary files differnew file mode 100644 index 000000000..e507dadbf --- /dev/null +++ b/doc/korganizer/organizer.png diff --git a/doc/korganizer/outlook-to-vcalendar.docbook b/doc/korganizer/outlook-to-vcalendar.docbook new file mode 100644 index 000000000..1c5d51eec --- /dev/null +++ b/doc/korganizer/outlook-to-vcalendar.docbook @@ -0,0 +1,283 @@ +<chapter id="outlook-to-vcalendar-ws"> + +<chapterinfo> +<authorgroup> + +<author> +<firstname>Randy</firstname> <surname>Pearson</surname> +<affiliation><address><email>blueboy@bamafolks.com</email></address></affiliation> +<contrib>Original author</contrib> +</author> + +<author> +<firstname>Klaus</firstname> <surname>Stärk</surname> +<affiliation><address><email>staerk@kde.org</email></address></affiliation> +<contrib>Additionals texts</contrib> +</author> + +<othercredit role="reviewer"> +<firstname>Eric</firstname> <surname>Bischoff</surname> +<affiliation><address><email>e.bischoff@noos.fr</email></address></affiliation> +<contrib>Editor</contrib> +</othercredit> + + +</authorgroup> + +<abstract> +<para>This version of the &korganizer; workshop <quote>Outlook +to vCalendar</quote> was released on October 17, 2002. See the +<filename>ChangeLog</filename> for details.</para> +<para>Please note that the descriptions and screenshots refer to version 3.1 of &korganizer;.</para> +</abstract> + +<keywordset> +<keyword>kdepim</keyword> +<keyword>KOrganizer</keyword> +<keyword>KOrganizer workshop</keyword> +<keyword>Outlook</keyword> +<keyword>vCalendar</keyword> +<keyword>Outlook2VCal</keyword> +</keywordset> + +<date>2002-10-17</date> +<releaseinfo>3.1</releaseinfo> +</chapterinfo> + +<title>KOrganizer workshop: Outlook to vCalendar</title> + +<sect1 id="outlook-to-vcalendar-overview"> +<title>Overview</title> + +<para> +When moving from &Microsoft; Outlook® to using &kde;'s &korganizer; +to manage schedules and appointments, you will probably wish to +export your scheduling data from Outlook® and import it into +&korganizer;. &Microsoft;'s Outlook® program does provide an export +option that can save an appointment to the industry standard vCalendar +format. +</para> + +<para> +Unfortunately, Outlook® will only export the appointment you have +selected, one at a time. This is fine if you only wish to transfer a +few appointments, but transferring the 200-300 appointments you may +have in your Outlook® folder would not be much fun. Therefore, +<ulink url="mailto:blueboy@bamafolks.com">Randy Pearson</ulink> created +a small application named <application>Outlook2VCal</application> that +can scan and export all the appointments to a vCalendar file at one time. +</para> + +</sect1> + +<sect1 id="outlook-to-vcalendar-installation"> +<title>Installation</title> + +<para> +The <application>Outlook2VCal 2.0</application> program is <ulink +url="http://korganizer.kde.org/learning/importdata.html">delivered as a compress +ZIP file</ulink>, which contains a <application>SETUP.EXE</application> +application. Merely extract the files using your favorite utility, +such as <ulink url="http://www.winzip.com">WinZip</ulink> and run the +<application>SETUP.EXE</application> program to install the program +on your Windows computer. This should be the same computer where you +normally run &Microsoft; Outlook 97®, 2000® or 2002®. +</para> + +<para> +Depending on how up to date your system is, you may or may not be prompted +to reboot during the installation. +</para> + +</sect1> + +<sect1 id="outlook-to-vcalendar-export"> +<title>Export Usage</title> + +<para> +After the program is installed, you can run it +by accessing <menuchoice><guimenu>Start</guimenu> +<guisubmenu>Programs</guisubmenu> <guisubmenu>Outlook2vCal</guisubmenu> +<guimenuitem>Outlook2vCal</guimenuitem></menuchoice>. You should see +this screen appear: +</para> + +<screenshot id="screenshot-outlook2vcal-main"> +<screeninfo>Outlook2VCal main window</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="o2v_main.png" format="PNG"/></imageobject> +<textobject><phrase>Outlook2VCal main window</phrase></textobject> +<caption><para>Outlook2VCal main window</para></caption> +</mediaobject> +</screenshot> + + +<para> +The program automatically attempts to communicate with Outlook® +using OLE Automation. If an error is reported, this probably means you +do not have Outlook® installed. +</para> + +<para> +You should first decide if you want to include information about holidays +in the exported file or not. Normally you will probably not wish to +do this, so the <guilabel>Skip Holidays</guilabel> box is checked by +default. Next, click the <guibutton>Export</guibutton> button, which will +display a standard <guilabel>File Save</guilabel> dialog box. Browse to +the desired folder and enter the filename where you wish to create +the new vCalendar data file. +</para> + +<screenshot id="screenshot-outlook2vcal-save"> +<screeninfo>Outlook2VCal Save File dialog</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="o2v_save.png" format="PNG"/></imageobject> +<textobject><phrase>Outlook2VCal Save File dialog</phrase></textobject> +<caption><para>Outlook2VCal Save File dialog</para></caption> +</mediaobject> +</screenshot> + +<para> +Depending on the security settings in Outlook®, you may see this +screen next. If so, be sure to allow access for a minute or two. +</para> + +<screenshot id="screenshot-outlook2vcal-warning"> +<screeninfo>Outlook2VCal Warning message</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="o2v_warning.png" format="PNG"/></imageobject> +<textobject><phrase>Outlook2VCal Warning message</phrase></textobject> +<caption><para>Outlook2VCal Warning message</para></caption> +</mediaobject> +</screenshot> + +<para> +The program will display progress messages in its main window as it +loads, converts and saves your appointments. Here is a final shot of +what a successful run looks like: +</para> + +<screenshot id="screenshot-outlook2vcal-progress"> +<screeninfo>Outlook2VCal Progress message</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="o2v_progress.png" format="PNG"/></imageobject> +<textobject><phrase>Outlook2VCal Progress message</phrase></textobject> +<caption><para>Outlook2VCal Progress message</para></caption> +</mediaobject> +</screenshot> + +</sect1> + +<sect1 id="outlook-to-vcalendar-import"> +<title>Import Usage</title> + +<para> +Now that you have exported Outlook's® appointments, the final step is +to load the appointments into &korganizer;. Transfer the file over to the +computer running &korganizer; (via network, floppy disk, whatever). Now, +run &korganizer;. If desired, you can create a new calendar, or open an +existing one. +</para> + +<screenshot id="screenshot-outlook2vcal-importing1"> +<screeninfo>Outlook2VCal Importing Data #1</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="o2v_importing1.png" format="PNG"/></imageobject> +<textobject><phrase>Outlook2VCal Importing Data #1</phrase></textobject> +<caption><para>Outlook2VCal Importing Data #1</para></caption> +</mediaobject> +</screenshot> + + +<para> +Now, choose the <menuchoice><guimenu>File</guimenu><guisubmenu>Import</guisubmenu> +<guimenuitem>Import Calendar</guimenuitem></menuchoice> menu item. Browse and/or enter +the name of the vCalendar file you just transferred to this computer. +</para> + +<screenshot id="screenshot-outlook2vcal-importing2"> +<screeninfo>Outlook2VCal Importing Data #2</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="o2v_importing2.png" format="PNG"/></imageobject> +<textobject><phrase>Outlook2VCal Importing Data #2</phrase></textobject> +<caption><para>Outlook2VCal Importing Data #2</para></caption> +</mediaobject> +</screenshot> + +<para>&korganizer; will ask you if you want to <guilabel>Add as new +calendar</guilabel>, which adds the calendar file as a new local file resource, +<guilabel>Merge into existing calendar</guilabel>, which merges the calendar +items into an existing resource or <guilabel>Open in separate window</guilabel>, +which will allow you to view and edit the calendar, but will not add to +its default view. To add the calendar items, select one of the two first +options, and press <guibutton>OK</guibutton>.</para> + +<para> +After you select the <guibutton>OK</guibutton> button, &korganizer; +will load the appointments from the file and update its calendar. +</para> + +<screenshot id="screenshot-outlook2vcal-importing3"> +<screeninfo>Outlook2VCal Importing Data #3</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="o2v_importing3.png" format="PNG"/></imageobject> +<textobject><phrase>Outlook2VCal Importing Data #3</phrase></textobject> +<caption><para>Outlook2VCal Importing Data #3</para></caption> +</mediaobject> +</screenshot> +<para> +Save your modified calendar and enjoy using &korganizer;! +</para> + +</sect1> + +<sect1 id="outlook-to-vcalendar-limitations"> +<title>Limitations</title> + +<para> +The first version of this program (1.0) was tested on &Microsoft; Windows +2000 Server® and Professional® running &Microsoft; Outlook 2000®. +When attempting to use &Microsoft; Outlook 97®, the program failed miserably. +</para> + +<para> +The second (2.0) version, is reported to work (at least) with &Microsoft; +Outlook 97®, 2000®, and 2002®. +</para> + +<para> +If anyone has a work around for this problem, feel free to send a note to +Randy Pearson (<email>blueboy@bamafolks.com</email>). +</para> + +</sect1> + +<sect1 id="outlook-to-vcalendar-credits"> +<title>Credits and license</title> + +<para>Contributors:</para> + +<variablelist> +<varlistentry> +<term>Original author</term> +<listitem><para>Randy Pearson + <email>blueboy@bamafolks.com</email></para></listitem> +</varlistentry> + +<varlistentry> +<term>Additionals texts</term> +<listitem><para>Klaus Stärk + <email>staerk@kde.org</email></para></listitem> +</varlistentry> + +<varlistentry> +<term>Conversion to DocBook</term> +<listitem><para>Eric Bischoff + <email>e.bischoff@noos.fr</email></para></listitem> +</varlistentry> +</variablelist> + + +</sect1> + +</chapter> diff --git a/doc/korganizer/plugins-chapter.docbook b/doc/korganizer/plugins-chapter.docbook new file mode 100644 index 000000000..34df8f5c3 --- /dev/null +++ b/doc/korganizer/plugins-chapter.docbook @@ -0,0 +1,48 @@ +<chapter id="plugins-chapter"> + +<title>Plugins</title> + +<para> +&korganizer; provides you the possibility of extending the application with plugins. +</para> + +<para> +The plugins can be configured under the &korganizer; main configuration dialog +Choose <menuchoice><guimenu>Settings</guimenu><guimenuitem> +Configure &korganizer;</guimenuitem></menuchoice> or +<menuchoice><guimenu>Settings</guimenu><guimenuitem> +Configure Calendar</guimenuitem></menuchoice>, inside &kontact;, and click the +<guilabel>Plugin</guilabel> icon on the icon list sidebar of the dialog. +</para> + +<sect1 id="plugins-chapter-availableplugins"> +<title>Available Plugins</title> + +<sect2 id="date-numbers-plugin"> +<title>Date Numbers Plugin for Calendars</title> +<para> +This plugin adds the day number of day in the the year to the agenda view. For +instance, February 1 is the day number 32. +</para> +</sect2> + +<sect2 id="jewish-calendar-plugin"> +<title>Jewish Calendar Plugin</title> +<para> +The plugin provides you a the the Jewish calendar dates in addition to the +Gregorian calendar dates. In the configuration dialog of the plugin, you can +choose if you want to display Israeli holidays, weekly prasha, day of Omer and / +or Chol HaMoed. +</para> +</sect2> + +<sect2 id="journal-print-plugin"> +<title>Journal Print Style</title> +<para> +The plugin allows you to print journal (diary) entries. +</para> +</sect2> + +</sect1> + +</chapter> diff --git a/doc/korganizer/remotefile-resource.png b/doc/korganizer/remotefile-resource.png Binary files differnew file mode 100644 index 000000000..eabf409c8 --- /dev/null +++ b/doc/korganizer/remotefile-resource.png diff --git a/doc/korganizer/todo-general.png b/doc/korganizer/todo-general.png Binary files differnew file mode 100644 index 000000000..6d620a76b --- /dev/null +++ b/doc/korganizer/todo-general.png diff --git a/doc/korn/Makefile.am b/doc/korn/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/korn/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/korn/index.docbook b/doc/korn/index.docbook new file mode 100644 index 000000000..9ac4d7d03 --- /dev/null +++ b/doc/korn/index.docbook @@ -0,0 +1,238 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY appname "&korn;" > + <!ENTITY package "kdepim"> + <!ENTITY % English "INCLUDE"> + <!ENTITY % addindex "IGNORE"> +]> + +<book lang="&language;"> +<bookinfo> +<title>The &korn; Documentation</title> + +<authorgroup> +<author> +<firstname>Nick</firstname> +<surname>Betcher</surname> +<affiliation> +<address><email>nbetcher@uswest.net</email></address></affiliation> +</author> + +<othercredit role="developer"> +<firstname>Sirtaj</firstname> +<surname>Kang</surname> +<affiliation> +<address><email>taj@kde.org</email></address> +</affiliation> +<contrib>Developer</contrib> +</othercredit> + +<othercredit role="developer"> +<firstname>Cristian</firstname> +<surname>Tibirna</surname> +<affiliation> +<address><email>tibirna@kde.org</email></address> +</affiliation> +<contrib>Developer</contrib> +</othercredit> + +<othercredit role="developer"> +<firstname>Kurt</firstname> +<surname>Granroth</surname> +<affiliation> +<address><email>granroth@kde.org</email></address> +</affiliation> +<contrib>Developer</contrib> +</othercredit> + +<othercredit role="developer"> +<firstname>Rik</firstname> +<surname>Hemsley</surname> +<affiliation> +<address><email>rik@kde.org</email></address> +</affiliation> +<contrib>Developer</contrib> +</othercredit> + +<othercredit role="reviewer"> +<firstname>Lauri</firstname> +<surname>Watts</surname> +<affiliation><address><email>lauri@kde.org</email></address></affiliation> +<contrib>Reviewer</contrib> +</othercredit> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-11-09</date> +<releaseinfo>0.03.00</releaseinfo> + +<copyright> +<year>2000</year> +<holder>Nick Betcher</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<abstract><para>This Documentation describes &korn; Version +0.2</para></abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KOrn</keyword> +<keyword>File searching</keyword> +</keywordset> +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&korn; is a KDE Mail Checker that has the capabilities to dock itself to +<application>Kicker</application>. &korn; can check the following types of +mailboxes:</para> + +<itemizedlist> +<listitem><para>mbox type +(<abbrev>i.e.</abbrev>:<filename>/var/spool/mail/root</filename>)</para></listitem> +<listitem><para>qmail</para></listitem> +<listitem><para>POP3</para></listitem> +<listitem><para>Imap4</para></listitem> +<listitem><para>nntp</para></listitem> +<listitem><para>and the ability to check on a process</para></listitem> +</itemizedlist> + +<para>&korn;, checks your mail on an interval that is user specified for each +separate account. Once mail is received you can have &korn; run a 3rd party +program of your wishes or change the color/icon of &korn; while docked in +&kicker;. In addition to this you can have &korn; run a program once you click +on the docked icon in &kicker;.</para> + +<para>The rest of this chapter relies on the user to &RMB; click on the &korn; +icon in the &kicker; panel to access the appropriate menus.</para> +</chapter> + +<chapter id="the-preferences-dialog"> +<title>The Preferences Dialog</title> + +<sect1 id="the-buttons"> + +<title>The buttons</title> + +<para>The <guilabel>Preferences</guilabel> window is the most powerful part of +&korn;. At a first glimpse you may underestimate its capabilities, but further +under-the-hood you will find many ways to use &korn;.</para> + +<para>The first tab lists your current mailboxes. As default &korn; installs +<quote>Inbox</quote> as the default mailbox. The default <quote>Inbox</quote> +may not fit most users needs. With this default mailbox in place &korn; will +check the path <filename +class="directory">/var/spool/mail/<replaceable>user</replaceable></filename> for +new mail.</para> + +<para>The <link linkend="the-new-dialog"><guibutton>New...</guibutton></link> +button will be covered in the next section. Please jump ahead if that is the +section you need assistance with.</para> + +<para>If you would like to remove the selected mailbox, click the +<guibutton>Remove</guibutton> button on the right. You can also copy the +selected mailbox if you don't wish to create two similar mailboxes twice.</para> + +<para>Finally, after you have created a mailbox (see the next section), you can +modify it by selecting the mailbox you wish to edit and then clicking +<guibutton>Modify...</guibutton>. This dialog contains the same options as +when you click <guibutton>New...</guibutton>.</para> + +</sect1> + +<sect1 id="the-display-tab"> + +<title>The <guilabel>Display</guilabel> Tab</title> + +<para>The display tab contains the options to change where &korn; will show +itself.</para> + +<para>The first option, <guilabel>Horizontal</guilabel>, will create a window +and the contents of the window will contain the options you specified in the +<guilabel>View</guilabel> tab (which you can get to by selecting your mailbox +and clicking <guimenuitem>Modify...</guimenuitem>). On the other hand, selecting +<guilabel>Docked</guilabel> will dock &korn; into the &kicker; panel.</para> + +<para>The option <guilabel>Vertical</guilabel> is similar to +<guilabel>Horizontal</guilabel>, except the accounts stack +vertically.</para> + +</sect1> +<sect1 id="the-new-dialog"> +<title>The <guilabel>New...</guilabel> Dialog</title> + +<para>The <guibutton>New...</guibutton> button will load a window showing you +what mailboxes can be created for checking on a interval. Select your +appropriate mailbox type. If you don't know what type you should use, and you +currently use <application>Netscape</application> to check your mail, use +POP3.</para> + +<para>Following that window the modify options appear, allowing you to change +all aspects of the mail checking, including interval.</para> + +<para>Each mailbox type (&ie;: Pop3, nntp, imap) has different server options, +but the rest of the options (including Poll, Commands, and View) are the same +(excluding mailbox type <quote>process</quote>). In these server options dialogs +you need to enter the appropriate information to fit your situation. Keep in +mind the default ports that are entered some of the server options tabs are the +normal ones used by the majority of the Internet.</para> + +<para>The commands <guilabel>Poll</guilabel> tab contains one option that +changes the time interval between each check. Keep in mind this is in seconds, +not minutes.</para> + +<para>Next, the <guilabel>view</guilabel> tab has options for changing the icon +or icon color while &korn; is docked in &kicker;. There are two options: +<guilabel>Use color</guilabel> or <guilabel>Use icon</guilabel>. Selecting +<guilabel>Use color</guilabel> will allow you to modify the colors. Selecting +<guilabel>Use icon</guilabel> will allow you to change which icon is used for +both <quote>Normal</quote> and <quote>New mail</quote>. Keep in mind that &korn; +can only use a icon or color, not both.</para> + +<para>In the commands tab you can specify a command to be run once you receive +new mail in the <guilabel>New mail</guilabel> line. Also, the +<guilabel>Click</guilabel> line can contain a command to be run when you +<mousebutton>left</mousebutton> click on &korn;.</para> + +</sect1> + +</chapter> +<chapter id="licenses-and-credits"> +<title>Credits and License</title> + +<para>&korn;. Program copyright 2000:</para> + +<itemizedlist> +<listitem><para>Sirtaj Singh Kang <email>taj@kde.org</email></para></listitem> +<listitem><para>Cristian Tibirna <email>tibirna@kde.org</email></para></listitem> +<listitem><para>Kurt Granoth <email>granroth@kde.org</email></para></listitem> +<listitem><para>Rik Hemsley <email>rik@kde.org</email></para></listitem> +</itemizedlist> + +<para>Documentation copyright 2000 Nick Betcher +<email>nbetcher@uswest.net</email></para> + +<para>We hope this documentation helped you. If you need to contact me, the +document writer, you can at nbetcher@uswest.net. If you wish to contact the +developers of &korn;, you can find their names in the <guimenuitem>About +Korn...</guimenuitem> option or above.</para> + +&underFDL; +&underGPL; + +</chapter> + + + +</book> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +End: +--> + diff --git a/doc/kpilot/Makefile.am b/doc/kpilot/Makefile.am new file mode 100644 index 000000000..171f575ce --- /dev/null +++ b/doc/kpilot/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/kpilot/address-app.png b/doc/kpilot/address-app.png Binary files differnew file mode 100644 index 000000000..171b60093 --- /dev/null +++ b/doc/kpilot/address-app.png diff --git a/doc/kpilot/conduit-knotes.png b/doc/kpilot/conduit-knotes.png Binary files differnew file mode 100644 index 000000000..723c8a6a0 --- /dev/null +++ b/doc/kpilot/conduit-knotes.png diff --git a/doc/kpilot/conduit-mal.png b/doc/kpilot/conduit-mal.png Binary files differnew file mode 100644 index 000000000..e72249945 --- /dev/null +++ b/doc/kpilot/conduit-mal.png diff --git a/doc/kpilot/conduit-palmdoc.png b/doc/kpilot/conduit-palmdoc.png Binary files differnew file mode 100644 index 000000000..196961bb4 --- /dev/null +++ b/doc/kpilot/conduit-palmdoc.png diff --git a/doc/kpilot/conduit-popmail-kmail.png b/doc/kpilot/conduit-popmail-kmail.png Binary files differnew file mode 100644 index 000000000..ad63b3597 --- /dev/null +++ b/doc/kpilot/conduit-popmail-kmail.png diff --git a/doc/kpilot/conduit-sysinfo.png b/doc/kpilot/conduit-sysinfo.png Binary files differnew file mode 100644 index 000000000..57b4534cd --- /dev/null +++ b/doc/kpilot/conduit-sysinfo.png diff --git a/doc/kpilot/conduit-vcal.png b/doc/kpilot/conduit-vcal.png Binary files differnew file mode 100644 index 000000000..13270cd40 --- /dev/null +++ b/doc/kpilot/conduit-vcal.png diff --git a/doc/kpilot/configuration.docbook b/doc/kpilot/configuration.docbook new file mode 100644 index 000000000..d6da8f14b --- /dev/null +++ b/doc/kpilot/configuration.docbook @@ -0,0 +1,1783 @@ +<chapter id="configure"> +<title>Configuring &kpilot;</title> + +<para> +Once &kpilot; is installed it needs to be +configured +to match your hardware. +The <link linkend="config-conduits">conduits</link> +need to be configured as well. +After that you can use &kpilot; +to synchronize your &PalmPilot; with +your &kde; desktop or view +data from your &PalmPilot; with the +<link linkend="builtin">built-in viewers</link>. +</para> + +<para> +When you run &kpilot; from either +the panel menu or from the command prompt for the first time +it will prompt you with +a dialog box to configure it. +This configuration dialog can be requested later +from the main application +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure &kpilot;</guimenuitem> +</menuchoice> +menu, from the &kpilot; daemon popup menu +<menuchoice> +<guimenuitem>Configure KPilot...</guimenuitem> +</menuchoice> +menu item or by starting &kpilot; +from the shell +as follows: +<screen width="40"><prompt>$ </prompt> <userinput><command>kpilot</command><option>--setup</option></userinput> +</screen> +In addition, if you upgrade &kpilot; and some new configuration +options require your attention, this setup dialog will reappear. +</para> + +<screenshot> +<screeninfo>Configuration Dialog</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="setup-tabs.png" format="PNG"/></imageobject> +<textobject><phrase>The configuration dialog</phrase></textobject> +<caption><para>The configuration dialog</para></caption> +</mediaobject> +</screenshot> + + +<para> +&kpilot;'s configuration dialog is a large one. +This is because it contains not only the configuration of the +device for communicating with the &PalmPilot;, but also +the configuration of all the installed conduits. +Each group of configuration options +(<link linkend="general-setup">general</link> +and <link linkend="config-conduits">conduits</link>) +will be discussed separately. +We will begin, however, by taking a look at the +<link linkend="configwizard">configuration wizard</link>, which should make most +of the +general group of configuration options superfluous. +</para> + +<sect1 id="configwizard"> +<title>Using the Wizard</title> + +<para> +The configuration wizard helps you to set up &kpilot; to communicate +with the &PalmPilot; and to configure the conduits as a group. It's a great +start for new users, and you can always fine-tune your preferences later. +</para> + +<para> +In the <guilabel>Pilot Info</guilabel> dialog, type your <guilabel>User +Name</guilabel>. It +should match the one from the &PalmPilot;. Next, type the file name of +the <guilabel>Device</guilabel> you will use to connect the &PalmPilot; (The +connection can be through a serial port, USB port, infrared, Bluetooth, network +or the generic <filename class="devicefile">/dev/pilot</filename> device.) +Alternatively, click the +<guibutton>Automatically detect handheld and user name...</guibutton> +button and press the &HotSync; button on your &handheld;. The Wizard will try +to find the correct <guilabel>Device</guilabel> and +<guilabel>User Name</guilabel>. +</para> + +<important><para> +If the +<guilabel>Device</guilabel> does not have the right permissions, the wizard will +not be able to find it. Normal users must be able to read/write the correct +device. To resolve this issue, please refer to <link +linkend="faq-connection"><quote>&kpilot; says <errorname>Can't connect to +pilot</errorname></quote> +&FAQ; entry</link>, or contact your system administrator. +</para></important> + + +<screenshot> +<screeninfo>The First Configuring Wizard Dialog</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="wizard-general.png" +format="PNG"/></imageobject> +<textobject><phrase>Configuring Wizard: The Pilot Info +Dialog</phrase></textobject> +<caption><para>Configuring Wizard: The Pilot Info Dialog</para></caption> +</mediaobject> +</screenshot> + +<para> +Press the &HotSync; button of your &handheld; to probe for the +correct <guilabel>Device</guilabel> and <guilabel>User Name</guilabel>. +</para> + + +<screenshot> +<screeninfo>The Second Configuring Wizard Dialog</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="wizard-connection.png" +format="PNG"/></imageobject> +<textobject><phrase>Configuring Wizard: The Autodetection +Dialog</phrase></textobject> +<caption><para>Configuring Wizard: The Autodetection Dialog</para></caption> +</mediaobject> +</screenshot> + +<para> +&kpilot; has the ability to sync the data on your &handheld; with +applications or files on your <acronym>PC</acronym>. The programs that +perform these actions are called conduits. The sync dialog configures +all applicable &kpilot; conduits to sync with widely used +<acronym>PIM</acronym> suites. You can fine-tune these settings later, from the +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure &kpilot;</guimenuitem> +</menuchoice> +menu. Please check the <link linkend="config-conduits">conduits +configuration</link> +section of this document for more information. +</para> + +<screenshot> +<screeninfo>The Third Configuring Wizard Dialog</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="wizard-conduits.png" +format="PNG"/></imageobject> +<textobject><phrase>Configuring Wizard: The Sync Dialog</phrase></textobject> +<caption><para>Configuring Wizard: The Sync Dialog</para></caption> +</mediaobject> +</screenshot> + + +</sect1> + + +<sect1 id="general-setup"> +<title>General Setup</title> + +<para> +The settings available in the &kpilot; configuration dialog +under the heading <guilabel>General Setup</guilabel> +give you detailed control over the operation of &kpilot;: +you can select a non-standard hardware device, +set special encodings for foreign-language &handheld;s, +and control how &kpilot; displays your data. There +are five items under the <guilabel>General Setup</guilabel> +heading. You may need to expand the <guilabel>General Setup</guilabel> +heading to see them. +</para> + +<screenshot> +<screeninfo>Items under General Setup</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="setup-items.png" format="PNG"/></imageobject> +<textobject><phrase>The items under General Setup</phrase></textobject> +<caption><para>The items under General Setup</para></caption> +</mediaobject> +</screenshot> + + +<sect2 id="page-general"> +<title>Device Setup</title> + +<para> +This is a setup page that contains options describing +the &PalmPilot; hardware, you, the user +and how you want the various parts of &kpilot; +to be started. +</para> + +<screenshot> +<screeninfo>Device Page</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="setup-general.png" format="PNG"/></imageobject> +<textobject><phrase>The Device Page</phrase></textobject> +<caption><para>The Device Page</para></caption> +</mediaobject> +</screenshot> + + +<variablelist> +<varlistentry> +<term><guilabel>Pilot device</guilabel></term> +<listitem> +<para> +The port that the cradle is connected to. +By default it is +set to <filename class="devicefile">/dev/pilot</filename> +which should be a symbolic link to the real port. +The port might be a serial port, in which case +<filename class="devicefile">/dev/pilot</filename> +should point to +something like +<filename class="devicefile">/dev/cuaa0</filename> +(in &FreeBSD;) or +<filename class="devicefile">/dev/ttyS0</filename> +(in &Linux;). +For &USB; devices, it can be more difficult to +determine where +<filename class="devicefile">/dev/pilot</filename> +should point. +It may be possible to configure your &USB; daemon +to set up the link automatically, so that +<filename class="devicefile">/dev/pilot</filename> +points to the right port no matter where you plug in your &PalmOS; device. +</para> + +<para> +<emphasis>Make sure the port has +the correct permissions.</emphasis> +It +must be read/write by all if &kpilot; is intended to be used by a +normal user! &kpilot; will complain if the permissions are wrong, but you +will need to fix the permissions by hand. This could be done by doing a +<userinput><command>chmod</command> <parameter>666</parameter> +<replaceable>device</replaceable></userinput> +as root where <replaceable>device</replaceable> is the correct port. + +To resolve this issue, please refer to <link +linkend="faq-connection"><quote>&kpilot; says <errorname>Can't connect to pilot +</errorname></quote> +&FAQ; entry</link>, or contact your system administrator. +</para> + + +<para> +You can also use network sync (with pilot-link 0.11.5 and later) +by entering <userinput>net:any</userinput> as the +device name. +</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Speed</guilabel></term> +<listitem> +<para> +Indicate the speed of the <emphasis>serial</emphasis> +connection to the &PalmPilot;. +It has no meaning for &USB; devices. +For an older model &PalmPilot;, choose 9600. +Newer models may be able to handle speeds up to +the maximum listed, 115200. +You can experiment with the connection speed: the &PalmPilot; +manual suggests starting at a speed of 19200 and trying faster +speeds to see if they work. +</para> +</listitem> +</varlistentry> + +<varlistentry><term><guilabel>Encoding</guilabel></term> +<listitem> +<para> +&PalmOS; devices are available in +many different languages. +If your device uses a different encoding than +ISO-latin1, you will need to select the +correct encoding from the list in order to +display special characters correctly. +If you can enter Russian in your &PalmPilot;, +select CP1251, for instance. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Pilot user</guilabel></term> +<listitem> +<para> +The user name of the &PalmPilot;. By default this name is the same as +your log on name. When you sync with the &PalmPilot; &kpilot; will +check to see if this name matches the one on the &PalmPilot;. If they do +not, you are asked to pick which you will use. If you pick the local +name, the &PalmPilot; will be changed to match. +The <guilabel>Pilot User</guilabel> entry is also used to name the folder that +stores the information from the &PalmPilot;. This folder is created in the +<filename class="directory">$KDEHOME/share/apps/kpilot/DBBackup/</filename> +folder, where the <filename class="directory">$KDEHOME</filename> environment +variable +(typically <filename class="directory">/home/Login Name/.kde/</filename>) +points to the folder that contains your configuration and data for the &kde; +applications. +</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="page-hotsync"> +<title>HotSync Setup</title> + +<para> +This page contains settings with which you can instruct &kpilot; to perform +special kinds of &HotSync;, as well as direct how conflicts during a &HotSync; +should be resolved. A conflict happens when both the desktop application and the +&handheld; application change the same data. +</para> + +<para> +&kpilot; interfaces with your &handheld; in two ways: using the +the conduits and the internal viewers. Conduits are plug-in programs which +extend the synchronization capabilities of &kpilot;. &kpilot; stores separate copies of +the databases and records for conduits, while the internal viewers and backup +operation share the same copy. This distinction is important to choose your +update method depending on your usage. If you use mainly the conduits to sync +your &handheld; with external programs, you may choose as default +synchronization method any option that runs the conduits. However, if you use mainly the +internal viewers, you need to update copy of the databases as well in order to +view and edit the information from your &handheld;, so running the conduits only +is not sufficient. +</para> + +<screenshot> +<screeninfo>The &HotSync; setup page</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="setup-hotsync.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>The &HotSync; Page</phrase> +</textobject> +<caption> +<para>The &HotSync; setup page</para></caption> +</mediaobject> +</screenshot> + + +<variablelist> +<varlistentry> + +<term><guilabel>Default Sync</guilabel></term> + +<listitem> +<para> +Select the type of synchronization that will be performed by default. +</para> + +<itemizedlist> + +<listitem> +<para> +<guilabel>HotSync</guilabel>: run all selected conduits, sync the databases +with a modified flag set, updating the modified records only. Performs a fast +backup, backing up only the databases that were modified. This option offers +a nice balance between speed and data safety. +</para> +</listitem> + +<listitem> +<para> +<guilabel>FastSync</guilabel>: Only synchronize those +databases that have conduits, and perform no backup of the data +on the &PalmPilot;, reducing greatly the time required for the sync +operation. This also means that if something goes wrong with your &PalmPilot;, +you may not be able to recover the databases. This is a classic +trade-off between speed and safety. +</para> +</listitem> + +<listitem> +<para> +<guilabel>FullSync</guilabel>: run all selected conduits, and sync all +databases, reading all records, and performing a full backup. It is the safest +option, but takes the longest time to complete, as it will merge all the records +from the &handheld; and your desktop. It is the &kpilot; equivalent of the Palm +SlowSync. +</para> +</listitem> + +<listitem> +<para> +<guilabel>Copy PC to handheld</guilabel>: run all conduits and sync all +databases, but instead of merging the information from both sources, copy the PC +data to the handheld. <emphasis>Use with care, as this option erases the changes +you made in your handheld since the last sync</emphasis>. +</para> +</listitem> + +<listitem> +<para> +<guilabel>Copy handheld to PC</guilabel>: run all conduits and sync all +databases, but instead of merging the information from both sources, copy the +handheld data to the PC. <emphasis>Use with care, as this option erases the +changes you made in your PC since the last sync</emphasis>. +</para> +<warning> +<para> +Remember, when &kpilot; does a &HotSync; and runs the conduits, +the databases in the internal viewers are <emphasis>not</emphasis> +updated. To update the internal viewers, use the FullSync or backup actions. +</para> +</warning> + +</listitem> + +</itemizedlist> + +</listitem> +</varlistentry> + + +<varlistentry> +<term><guilabel>Do full backup when changing PCs</guilabel></term> +<listitem> +<para> +If you &HotSync; your &handheld; with multiple <acronym>PC</acronym>s, the flag +on the &handheld; that stores which +records have changed since the last &HotSync; may be inaccurate. It is +recommended to do a full sync when changing <acronym>PC</acronym>s. You can +disable the full sync by unchecking this box. +</para> +</listitem> +</varlistentry> +<!-- +<varlistentry> +<term><guilabel>Do not sync when screen saver is active</guilabel></term> +<listitem> +<para> +This is a security feature that prevents the &handheld; from synchronization +while the PC screen saver is active. This prevents other people from +stealing your data through the &handheld; cradle while your PC is +unattended. The feature only works with the &kde; screen savers, though, +and you will need to disable it to use &kpilot; in non-&kde; environments. +</para> +</listitem> +</varlistentry> +--> +<varlistentry> +<term><guilabel>Conflict Resolution</guilabel></term> +<listitem> +<para> +Data records can be changed both on the &handheld; and +on the <acronym>PC</acronym>. If one record has incompatible changes +in both the &handheld; and the <acronym>PC</acronym>, (such as +changing a phone number in different ways on both sides), +the conflicting change needs to be resolved so +that the &handheld; and the <acronym>PC</acronym> data are consistent again. +Choices for conflict resolution are: +</para> +<itemizedlist> +<listitem><para><guilabel>Ask User</guilabel>: +pop up a dialog for the user to +choose how the conflict is to be resolved for +every conflict. +</para></listitem> +<listitem><para><guilabel>Do Nothing</guilabel>: + leave the entries in an inconsistent state. +Future syncs may not notice the discrepancy. +</para></listitem> +<listitem><para><guilabel>Handheld Overrides</guilabel>: +copy the values from the &handheld; to the <acronym>PC</acronym>, +discarding the changes on the <acronym>PC</acronym>. +</para></listitem> +<listitem><para><guilabel>PC Overrides</guilabel>: +copy the values from the <acronym>PC</acronym> to the &handheld;, +discarding changes on the &handheld;. +</para></listitem> +<listitem><para><guilabel>Values From Last Sync (if possible)</guilabel>: +&kpilot; stores a backup copy of the information on your &handheld; depending on +the synchronization method you selected. If this information is available, use +neither +the values from the &handheld; nor the PC, but the values from +the last sync. +</para></listitem> +<listitem><para><guilabel>Use Both Entries</guilabel>: +Create duplicate entries of the conflicting records on both the +<acronym>PC</acronym> and +&handheld;, one with the value from the <acronym>PC</acronym>, the other with +the value +from the &handheld;. +</para></listitem> +</itemizedlist> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + + +<sect2 id="page-backup"> +<title>Backup Setup</title> + +<para> +This page contains settings specific to the backup operation, which saves +a copy of the the &handheld; databases, allowing the user to +restore this information later. +</para> + +<para>In short, databases are all files stored in your &handheld;. A database +can be either a record database, which stores dynamic information created by the +user (for instance, the addresses or the todo information), or a resource +database, which tend to be static (for instance the applications).</para> + +<screenshot> +<screeninfo>Backup Page</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="setup-dbspecial.png" format="PNG"/> +</imageobject> +<textobject><phrase>The Backup Page</phrase></textobject> +<caption><para>The Backup Page</para></caption> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Databases</guilabel></term> +<listitem> +<para> +List databases that should not be synced or backed up. +</para> + +<para> +The values can be either database creator values, which are 4-letter strings +surrounded by square brackets (so for Handbase databases you fill in +<userinput>[PmDB]</userinput>), or database names, +which are strings without square brackets that may contain shell-style +wildcards. +See the <link linkend="dbskip">FAQ</link> +for a list of databases that should be listed +here (the default should be OK though). +Newer &PalmPilot; devices contain emulation code for +the older 68k processor; this means that they have a large +number of databases with names ending in +<literal role="extension">_a68k</literal>. +These do not need to be backed up nor synced, so you could +add <userinput>*_a68k</userinput> +to the list of databases to skip. + +<itemizedlist> +<listitem><para> +<guilabel>No backup</guilabel> List here databases that should be excluded from +the backup operation. Some databases do not follow the standard database layout, +and trying to backup and restore them will result in information loss. You may +include here databases with volatile information, such as news or web pages, +that +often do not require to be backed up. +</para> +</listitem> + +<listitem><para> +<guilabel>Not restored</guilabel> List here databases that should be excluded +from the restore operation, even if they were previously backed up. Databases +included here can be installed manually later, using the +<guilabel>File Installer</guilabel>. You may +include here databases with volatile information, such as news or web pages, +that +often do not require to be restored. +</para></listitem> +</itemizedlist> + +<warning> +<para> +Changing the contents of the <guilabel>No backup</guilabel> +or <guilabel>Not restored</guilabel> fields, in particular removing +the databases already listed there, can damage those databases +when you perform a &HotSync;. +</para> +</warning> + +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Run conduits during a backup</guilabel></term> +<listitem> +<para> +The backup typically updates the copy of the &handheld; databases. +Conduits are programs that extend the &kpilot; functionality. Running them +usually means synchronization the &handheld; to other <acronym>PC</acronym> +databases, +like the address book or the calender. Check this box to perform both operations +on +every backup. +</para> +</listitem> +</varlistentry> + + +</variablelist> + +</sect2> + + +<sect2 id="page-viewers"> +<title>Internal Viewers Setup</title> +<para> +&kpilot; contains <quote>viewers</quote> for +presenting information from the &PalmPilot;. +These viewers present the databases available on +the &PalmPilot; in much the same way that the device +itself does. Not all databases have an application-specific +viewer, though you can use the generic database viewer for those. +The viewers page contains settings for the internal viewers in +&kpilot;. +These settings change the way in which the data is shown. +</para> + +<screenshot> +<screeninfo>Viewers Page</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="setup-viewer.png" format="PNG"/></imageobject> +<textobject><phrase>The Viewers Setup Page</phrase></textobject> +<caption><para>The Viewers Setup Page</para></caption> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Make internal viewers editable</guilabel></term> +<listitem><para> +The internal viewers can be read only or editable. The editable mode allows you +to add new records, delete or edit the existing records and sync your +modifications back to the &handheld;. Check +this box to set the internal viewers to editable mode, uncheck to set them to +read +only mode.</para> +<warning><para> +On some &kpilot; versions, it is not possible check this box, and therefore to +use the internal viewers as editors. +</para></warning> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show private records</guilabel></term> +<listitem><para> +In your &PalmPilot; you can mark some records as <quote>private</quote>. By +default, &kpilot; does not display these records on the screen. Check this box +if you want to see them. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Address Viewer</guilabel></term> +<listitem><para> +Set there the options for the address internal viewer. + +<itemizedlist> +<listitem><para> +<guilabel>Show as "Last, first"</guilabel> or +<guilabel>Show as "Company, last"</guilabel>: the order and display of the +address records in the address internal viewer can be set to match the +&handheld;. Select the option that suits better your personal preferences. +</para></listitem> + +<listitem><para> +<guilabel>Use key field</guilabel> Check this box to combine entries with the +same last name. +</para></listitem> + +</itemizedlist> + +</para></listitem> +</varlistentry> + + +</variablelist> + +</sect2> + + + +<sect2 id="page-startup-exit"> +<title>Startup and Exit Behavior Setup</title> + +<para> +This pages present options related to the startup and exit of &kpilot; and +&kpilot; daemon. +</para> + +<para> +While &kpilot; is the front-end for the internal viewers, configuration options +and logs, the sync operation is handled by the &kpilot; daemon. Even if &kpilot; +is not running you can &HotSync; if the daemon is. Therefore, if you want to +be able to sync your &handheld; at anytime, it is important to start the daemon +at login, or the opposite, if you want to be able to sync only when &kpilot; is +running, you have to stop the daemon on exit. The last option is especially +usefull if you have other applications that use the same port as &kpilot;. +</para> + + +<screenshot> +<screeninfo>Startup and Exit Page</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="setup-startup-exit.png" +format="PNG"/></imageobject> +<textobject><phrase>The Startup and Exit Page</phrase></textobject> +<caption><para>The Startup and Exit Page</para></caption> +</mediaobject> +</screenshot> + + +<variablelist> + +<varlistentry> +<term><guilabel>Startup Options</guilabel></term> + +<listitem> +<para> + +<itemizedlist> +<listitem> +<para> +<guilabel>Start daemon at login</guilabel>: +By checking this, a link to +the daemon is placed in your autostart folder +and will be started automatically. Note that this is not normally +needed if the daemon is docked in the panel. +<!-- TODO: broken functionality --> +</para> +</listitem> + +<listitem> +<para> +<guilabel>Show daemon in panel</guilabel>: +Check this box to instruct the daemon to place a &kpilot; icon +<guiicon> +<inlinemediaobject> +<imageobject><imagedata fileref="kpilot.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</guiicon> +in the system tray. This icon has a menu that can be brought up with +the right mouse button. Without this option, the daemon is not visible to the +user at all. +</para> +</listitem> +</itemizedlist> + +</para> +</listitem> + +</varlistentry> + +<varlistentry> + +<term> +<guilabel>Exit Options</guilabel> +</term> + +<listitem> +<para> + +<itemizedlist> +<listitem> +<para> +<guilabel>Quit after HotSync</guilabel>: When this option is enabled, both +&kpilot; and the &kpilot; daemon will exit after the &HotSync; operation has +completed, leaving the device port free for other tools. This may be needed on +systems where the &USB; daemon starts &kpilot; automatically. +</para> +</listitem> + +<listitem> +<para> +<anchor id="stopdaemononexit"/> +<guilabel>Stop daemon on exit</guilabel>: Setting this option will cause the +daemon to exit when you quit &kpilot;, leaving the device port free for other +&PalmPilot;-synchronization tools such as <application>malsync</application> +</para> +</listitem> +</itemizedlist> +</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> +</sect1> + +<sect1 id="config-conduits"> +<title>Conduits Setup</title> + +<para> +Conduits are programs that interface your &handheld; data with +<acronym>PC</acronym> applications or sync your &handheld; data with files +that can be used by <acronym>PC</acronym> applications. They can be +written by third parties, to interface your &PalmPilot; to any application +imaginable. +</para> + +<para> +&kpilot;'s configuration dialog allows you to select which conduits +to run during a &HotSync; and to configure those conduits. +A window similar to the following will be displayed: +</para> +<screenshot> +<screeninfo>The Conduit Setup Dialog</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="setup-conduit.png" format="PNG"/></imageobject> +<textobject> +<phrase>The Conduit Setup Dialog</phrase> +</textobject> +<caption> +<para>The Conduit Setup Dialog</para> +</caption> +</mediaobject> +</screenshot> +<para> +Check the box to the left of the conduit name to make it active, uncheck to make +it inactive or click on the conduit name to configure it. +</para> + +<variablelist> + +<varlistentry> +<term><guilabel>KNotes / Memos</guilabel></term> +<listitem> +<para> +Synchronizes the Memo Pad application with &knotes;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Notepad</guilabel></term> +<listitem> +<para> +Exports the free hand notes of the &handheld;'s Notepad application as pictures +to the PC. +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term><guilabel>Time Synchronization</guilabel></term> +<listitem> +<para> +Sets the &handheld;'s time to that of the desktop machine. +Useful for keeping the clock of the &handheld; accurate. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Calendar (KOrganizer)</guilabel></term> +<listitem> +<para> +Synchronizes the Datebook application with &korganizer; or with an +iCalendar file of +your choice. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Palm DOC</guilabel></term> +<listitem> +<para> +Automatically converts and installs text files in the &PalmPilot; +DOC format, so you can read the text files with most DOC-capable +applications on the &handheld;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Addressbook</guilabel></term> +<listitem> +<para> +Synchronizes the Address application with &kaddressbook; or with a vCard file of +your choice. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>System Information</guilabel></term> +<listitem> +<para> +Writes information about your &handheld;, (such as OS version, +RAM available, and the list of databases) to a file. Useful mostly for +debugging purposes. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>ToDo's (KOrganizer)</guilabel></term> +<listitem> +<para> +Synchronizes the Todo list application with &korganizer; or with a iCalendar +file of +your choice. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>MAL (AvantGo) Conduit</guilabel></term> +<listitem> +<para> +Synchronizes your &handheld; with the &AvantGo; server. The &AvantGo; server +offers general content (news, guides, stock quotes, &etc;) in a format that is +suitable for reading in a &handheld;. To use this conduit, you need to register, +subscribe +the channels you select and install the &AvantGo; software on your &handheld;. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Mail</guilabel></term> +<listitem> +<para> +Sends mail written on the &handheld; through &kmail;. +There is no provision for receiving mail, however. +</para> +</listitem> +</varlistentry> + +</variablelist> + + +<sect2 id="conduit-knotes"> +<title>&knotes; Conduit Setup</title> + +<para> +The &knotes; Conduit is a partial replacement for the built-in <link +linkend="builtin">memo application</link>. It keeps the notes you write +with &knotes; synchronized with the memos you write on your &PalmPilot;. +</para> + +<para> +Setting up the &knotes; conduit is very simple. +</para> + +<screenshot> +<screeninfo>&knotes; Conduit Setup</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="conduit-knotes.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>&knotes; Conduit Setup</phrase> +</textobject> +<caption> +<para>&knotes; Conduit Setup</para> +</caption> +</mediaobject> +</screenshot> + +<para> +In the <guilabel>General</guilabel> Tab there are two configuration options: + +<variablelist> + +<varlistentry> +<term><guilabel>Delete KNote when Pilot memo is deleted</guilabel></term> +<listitem> +<para> +Uncheck this box if you wish to maintain the note on &knotes; even if the +correspondent memo was deleted on the &handheld; memo application. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Suppress delete-confirmation in KNotes</guilabel></term> +<listitem> +<para> +If the <guilabel>Delete KNote when Pilot memo is deleted</guilabel> box is +checked, you may check this box to automatically delete the notes that +correspond to a deleted memo, without confirmation. +</para> +</listitem> +</varlistentry> + +</variablelist> + +<note> +<para> +By default, the options <quote>delete knote</quote> and <quote>suppress +delete-confirmation</quote> are turned <emphasis>off</emphasis>, so that notes +will accumulate on your PC. +</para> +</note> + +</para> +</sect2> + +<sect2 id="notepad-cond"> +<title>Notepad Conduit Setup</title> + +<para> +The Notepad Conduit exports the free hand notes of the &handheld;'s Notepad +application as pictures to the desktop. To set the folder to which the pictures +should be exported, either enter it in the <guilabel>Output</guilabel> edit +box or select it clicking the file picker button. +</para> + +</sect2> + +<sect2 id="time-cond"> +<title>Time Synchronization Conduit Setup</title> + +<para> +The Time Synchronization Conduit syncs the &handheld;'s time to that of the +desktop +machine. It is useful for keeping the clock of the &handheld; accurate. There +are really no configuration options other that enabling and disabling the +conduit, as currently only one direction for the synchronization is enabled, +you can only <guilabel>Set the handheld time from the time on the PC</guilabel>, +and not <guilabel>Set the PC time from the time on the handheld</guilabel>. +</para> + + +<note> +<para> +&PalmOS; Version 3.25 and 3.3 do not support setting the &handheld; system time. +For these systems, the conduit will be simply skipped. +</para> +</note> + +</sect2> + +<sect2 id="vcal-cond"> +<title>Calendar Conduit Setup</title> + +<para> +This conduit will synchronize your &PalmPilot; with &korganizer; and &kontact; +or to an iCalendar file of your choice. In the latter case, the conduit will +need the filename of the calendar file (this will usually be a file that ends in +<literal role="extension">.ics</literal>) to sync with, of if it uses the +standard &korganizer; iCalendar file, it will be under the <filename +class="directory">$KDEHOME/share/apps/korganizer/</filename> folder, where the +<filename class="directory">$KDEHOME</filename> environment variable (typically +<filename class="directory">/home/user/.kde/</filename>) points to the folder +that contains your configuration and data for the &kde; applications. +</para> + +<screenshot> +<screeninfo>The Calendar Conduit Setup Dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="conduit-vcal.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Calendar Conduit Setup</phrase> +</textobject> +<caption> +<para>Calendar Conduit Setup</para> +</caption> +</mediaobject> +</screenshot> + +<para> +In the <guilabel>General</guilabel> page, you can set the calendar options. +</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Calendar Destination</guilabel></term> +<listitem> +<para> +Choose between synchronizing with the <guilabel>Standard Calendar</guilabel>, +or in other words, the &korganizer; standard calendar or with a +<guilabel>Calendar file</guilabel> of your choice, that you must either +write in the <guilabel>Calendar file</guilabel> edit box or select using the +file picker. +</para> + +<warning> +<para> +You can use the calendar conduit with any application that accepts a file in +the iCalendar format as a resource. However, some applications, like Evolution, +do not handle the synchronization gracefully while they are open. As a rule of +thumb, quit these applications before synchronizing, otherwise you will lose +data. There is no need to take these precautions when syncing with &korganizer; +or &kontact;. +</para> +</warning> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Store archived records in the KDE calendar</guilabel></term> +<listitem> +<para> +Check this box to save a copy of the archived records from your +&handheld; on the <acronym>PC</acronym>, in order to keep a history of +past appointments in you &kde; desktop as well. +</para> +</listitem> +</varlistentry> + +</variablelist> + +<para> +In the <guilabel>Conflicts</guilabel> page, you can set the calendar options, +overriding &kpilot;'s general settings for conflict resolution when you are +using this conduit. For a detailed description of the different conflict +resolution possibilities available, please refer to the <link +linkend="page-hotsync">HotSync Setup section</link> of this handbook. +</para> + +</sect2> + + +<sect2 id="conduit-palmdoc"> +<title>Palm DOC Conduit Setup</title> + +<para> +The Palm DOC conduit converts text files in your <acronym>PC</acronym> from and +to +databases in Palm DOC format in the &PalmPilot;. You can use any Palm DOC reader +to view these files on your &PalmPilot;. +</para> + +<screenshot> +<screeninfo>Palm DOC Conduit Setup</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="conduit-palmdoc.png" +format="PNG"/></imageobject> +<textobject><phrase>Palm DOC Conduit Setup</phrase></textobject> +<caption><para>Palm DOC Conduit Setup</para></caption> +</mediaobject> +</screenshot> + +<important><para> +After changing the Palm DOC conduit configuration, you have to restart &kpilot; +to let the changes you made take effect. +</para></important> + +<para> +In the <guilabel>General</guilabel> page, you can set the location of the text +documents in your computer and the direction of the synchronization. +</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Text files:</guilabel></term> +<listitem><para> +Type on the text box or use the file picker to select the location of the folder +that the Palm DOC conduit uses a as the place for the text files it will sync +with the &handheld;. There, you may place the text documents you want install or +synchronize to the <acronym>PDA</acronym>, and find the text documents created +from Palm DOC +databases in your &handheld;. +<important><para> +The file name has to end in <literal role="extension">.txt</literal> for the +conduit to recognize it as text. If the file is not recognized as text, it will +be ignored by the conduit. Also, the text has to be in an encoding that is +compatible with your &handheld; encoding. Therefore, if the text file has +characters that are not being correctly recognized by the Palm DOC reader in +your &handheld;, try opening the file a text editor, like &kwrite;, and saving +it in an compatible text encoding using the <guilabel>Save As..</guilabel> +dialog, or set the encoding in the <guilabel>PC -> Handheld</guilabel> tab. +</para></important> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Local copy:</guilabel></term> +<listitem><para> +If you want to save a copy of the Palm DOC databases from your &handheld; in +your computer, check the <guilabel>Local copy:</guilabel> box and +type on the text box or use the file picker to select the location of the folder +where these databases will be saved. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Synchronization Mode</guilabel></term> +<listitem><para> +The Palm DOC conduit has the ability to sync from and to the &handheld;, +automatically converting the text files to Palm DOC databases and vice versa. +The <guilabel>Sync only PC to PDA</guilabel> option will convert all text files +located in the folder you selected above to Palm DOC databases and install them +in your &handheld;. +The <guilabel>Sync only PDA to PC</guilabel> option will convert all Palm DOC +databases from your &handheld; to files and install them in the +folder you selected above. Finally, The <guilabel>Sync all</guilabel> option +allows the synchronization to work in both directions. + +<note><para> +When both the text file and the Palm DOC database are modified, you cannot merge +the modifications, you have to choose one of the versions, losing the changes +in one of them. +</para></note> +</para></listitem> +</varlistentry> + +</variablelist> + +<para> +In the <guilabel>PC -> Handheld</guilabel> page, you can configure the Palm DOC +compression and bookmarks settings to use when converting from text files to +Palm DOC databases. +</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Compress</guilabel></term> +<listitem><para> +Palm DOC documents can be compressed, saving considerable amounts +of available memory in your &handheld;. Most Palm DOC readers support +compressed documents, but if you use a reader or editor that is not compatible +with compression (for instance, the Sied editor), you will not be able to read +or edit the compressed Palm DOC documents created by this conduit. +Therefore, check this box to save &handheld; memory, but uncheck it if you have +compatibility problems with compressed Palm DOC in your favorite editor or +reader. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Convert bookmarks</guilabel></term> +<listitem><para> +The Palm DOC format has a provision for bookmark records. Bookmarks allow you to +easily jump to selected parts of the document, making browsing long documents +easier. Check this box to allow the Palm DOC conduit to create bookmark records. +To create them, the conduit has to know the location in the text and the name of +the bookmark. There are three supported ways to let the conduit know the +location and name of the bookmark: from inline tags in the text, from tags at +the end of the text and from a <literal role="extension">.bmk</literal> bookmark +file. To make the creation of bookmarks effective, you have to check at least +one of these boxes below. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Inline tags in text</guilabel></term> +<listitem><para> +Convert tags in the format <* <replaceable>BookmarkName</replaceable> *> +located inside the text to Palm DOC bookmarks, where the location of the +tag in the text will be converted to the bookmark location and the +<replaceable>BookmarkName</replaceable> text inside the tag will be converted to +the name of the bookmark in the Palm DOC format. The tag will be removed from +the resulting Palm DOC document, leaving the text clean. +This is a very easy and intuitive way to create bookmarks +in your Palm DOC documents. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Tags at end of text</guilabel></term> +<listitem><para> +Convert tags in the format <<replaceable>BookmarkName</replaceable>> +located in the end of the text to Palm DOC bookmarks. Whenever the +<replaceable>BookmarkName</replaceable> text appears in the text, the conduit +will generate a the bookmark in the resulting Palm DOC document pointing to it. +The tag will then be removed from the resulting Palm DOC document, leaving the +text clean. This is a simple way to create repetitive bookmarks, like one for +each <quote>Chapter</quote> in your Palm DOC documents. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Regular expressions in .bmk file</guilabel></term> +<listitem><para> +This is the most complex but the most powerful way to create bookmarks. +The method involves using regular expressions (QRegExp) in a file +<filename>TextName.bmk</filename>, where <filename>TextName.txt</filename> is +the filename of the text, to search the text for bookmarks. See the +<ulink +url="http://reinhold.kainhofer.com/Linux/KPilot/bmkSpecification.txt"> +documentation</ulink> +for an in-depth description of the bmk file format. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Encoding</guilabel></term> +<listitem><para> +Set here the encoding of your &handheld;. &kpilot; will convert the text +document to this encoding when exporting the file to the &handheld;. +</para></listitem> +</varlistentry> + +</variablelist> + +<para> +In the <guilabel>Handheld -> PC</guilabel> page, you can configure bookmarks +settings to use when converting from Palm DOC databases to text files. +</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Convert Bookmarks</guilabel></term> +<listitem> +<para> +The Palm DOC format has a provision for bookmark records. Bookmarks allow you to +easily jump to selected parts of the document, making browsing long documents +easier. The Palm DOC conduit can convert Palm DOC +bookmark records to a format that is readable in your computer, either as +a separate file or as tags in the middle of the text file. Select +<guilabel>Do not convert bookmarks</guilabel> if you want to ignore the Palm DOC +bookmarks, resulting in a text that is clean from bookmark tags.</para> + +<para> +The <guilabel>Convert into .bm file</guilabel> options also result in a clean +text file, as the bookmarks are converted to a separate file in the bmk format, +as described <ulink +url="http://reinhold.kainhofer.com/Linux/KPilot/bmkSpecification.txt">here</ulink>. The file is saved with a <literal role="extension">.bm</literal> +extension to avoid conflicts with <literal role="extension">.bmk</literal> files +created previously.</para> + +<para>Finally, the <guilabel>Convert as inline tags</guilabel> option creates +inline tags inside the resulting text file form <* +<replaceable>BookmarkName</replaceable> *> placing each tag in the place that +was previously referenced by the bookmark, and using the bookmark name as the +<replaceable>BookmarkName</replaceable> text inside the tag. Now you You can +edit the bookmark name, move it or delete it and convert back to Palm DOC, as +you wish. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Do not convert, if text unchanged (only +bookmarks)</guilabel></term> +<listitem> +<para> +If you check this box, only changes in the text will trigger conversions from +Palm DOC to text files. In other words, changes in the bookmarks only will not +result in updates for the text files in your computer. +</para> +</listitem> +</varlistentry> + +</variablelist> + +<para> +In the <guilabel>Conflicts</guilabel> page, you can configure how the conduit +deals with files that changed both in the computer and the &handheld;. +</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Conflict Resolution</guilabel></term> +<listitem><para> +The Palm DOC conduit does not feature merging the modifications when a text is +changed both in the &handheld; and in the computer. Therefore, the choice is +between working with the files out of sync, or discarding the changes in one of +them. The <guilabel>No resolution</guilabel> option will avoid synchronizing +texts with conflicts, the <guilabel>PDA overrides</guilabel> option will +overwrite the computer text file version in case of conflict, +the <guilabel>PC overrides</guilabel> will do the same, but the other way +around, +and the <guilabel>Ask the user</guilabel> option will bring a dialog to let the +user decide on a file by file, case by case basis. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Always show resolution dialog, even when there are no +conflicts</guilabel></term> +<listitem><para> +This option will always bring the conflict resolution dialog, even if there is +no conflicts to solve. The advantage is that you can keep track of all the files +that are being covered by the conduit. +</para></listitem> +</varlistentry> + +</variablelist> + + +</sect2> + + +<sect2 id="conduit-kaddressbook"> +<title>&kaddressbook; Conduit Setup</title> + +<para> +This conduit will synchronize your &PalmPilot; with the &kde; address book or to +a vCard file of your choice. In the latter case, the conduit will need the +filename of the +vCard file (this will usually be a file that ends in <literal +role="extension">.vcf</literal>) to sync with, of if it uses the standard +&kde; address book file, it will be under the +<filename class="directory">$KDEHOME/share/apps/kabc/</filename> +folder, where the <filename class="directory">$KDEHOME</filename> environment +variable (typically <filename class="directory">/home/Login Name/.kde/</filename>) +points to the folder that contains your configuration and data for the &kde; +applications. +</para> + +<screenshot> +<screeninfo>The &kaddressbook; Conduit Setup Dialog</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="setup-address.png" format="PNG"/></imageobject> +<textobject><phrase>&kaddressbook; Conduit Setup</phrase></textobject> +<caption><para>&kaddressbook; Conduit Setup</para></caption> +</mediaobject> +</screenshot> + +<para> +In the <guilabel>General</guilabel> page, you can set the general address sync +options. +</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Sync Destination</guilabel></term> +<listitem><para> +Choose between synchronizing with the <guilabel>Standard address book</guilabel>, +or in other words, the &kde; standard address book or with a +<guilabel>vCard file</guilabel> of your choice, that you must either +write in the <guilabel>vCard file</guilabel> edit box or select using the +file picker. +</para> +<warning><para> +You can use the address book conduit with any application that accepts a file in +the vCard format as a resource. However, some applications may not handle +the synchronization gracefully while they are open. As a rule of thumb, +quit these applications before synchronizing, otherwise you may lose data. +There is no need to take these precautions when syncing with the &kde; address +book. +</para></warning> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Store archived records in the KDE address book</guilabel></term> +<listitem><para> +The &handheld; offers an option to archive deleted addresses in your desktop. +If that option is selected, check this box to keep the deleted addresses from +your &handheld; in your <acronym>PC</acronym> address book. These addresses will +be no longer synchronized with your handheld. +</para></listitem> +</varlistentry> + +</variablelist> + +<para> +In the <guilabel>Conflicts</guilabel> page, you can set the address book conduit +options, overriding &kpilot;'s general settings for conflict resolution when +you are using this conduit. For a detailed description of the different conflict +resolution possibilities available, please refer to the +<link linkend="page-hotsync">HotSync Setup section</link> of this handbook. +</para> + +<para> +In the <guilabel>Fields</guilabel> page, you can set the conduit options for +synchronizing the &handheld; address fields that do not have a direct +counterpart in the &kde; address book. +</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Handheld other phone:</guilabel></term> +<listitem><para> +The <quote>Other</quote> field in the &handheld; address application can be +used for many things (for instance storing a secondary email address). It is +not clear how to classify this field in &kde;. Depending on your usage, select +in +the dropdown the field from the computer that will be synchronized with the +<quote>Other</quote> field from your &handheld;. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Handheld street address:</guilabel></term> +<listitem><para> +While the <quote>Address</quote> field in the &handheld; address +application is the only default option for storing an street address, the &kde; +street address field can be a home address or a business address. The preferred +address will have precedence over other addresses, and the conduit will try to +set +this status by default. Either the home or business street address will be used +to +store the &handheld; street address. Select in the dropdown the option that +suits better your needs. For instance, if you use this field mainly for business +addresses, select <guilabel>Preferred, then Business Address</guilabel>. If not, +select <guilabel>Preferred, then Home Address</guilabel>. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Handheld fax:</guilabel></term> +<listitem><para> +While the <quote>Fax</quote> field in the &handheld; address +application is the only default option for storing a fax number, the &kde; +address book can store a home fax or a business fax number. Select in the +dropdown the option that suits better your needs. For instance, if you use this +field mainly for business faxes, select <guilabel>Business Fax</guilabel>. If +not, +select <guilabel>Home Fax</guilabel>. +</para></listitem> +</varlistentry> + +</variablelist> + +<para> +In the <guilabel>Custom Fields</guilabel> page, you can set the conduit options +for +dealing with the <quote>Custom</quote> fields from your &handheld; address +application. Since there are no natural correspondence between these fields and +other &kde; address book fields, you can set them as you like. You can use them +to store a <guilabel>URL</guilabel>, a <guilabel>IM Address</guilabel>, +the <guilabel>Birthdate</guilabel> of your contact or the obvious: +<guilabel>Store as Costume Field</guilabel>. +</para> + +<para> +If you select to store birthdays, remember to use a date format that is +consistent with the settings in the <guilabel>Date format</guilabel> dropdown, +so that the conduit can correctly identify the date from the record and vice +versa. Possible placeholders are: %d for the day, %m for the month, %y for the +two-digit year, %Y for the four-digit year. For example, %d.%m.%Y would +generate a date like 27.3.1952, while %m/%d/%y would write the same date as +03/27/52. +</para> + + +</sect2> + +<sect2 id="sysinfo-cond"> +<title>System Information Conduit Setup</title> + +<para> +This conduit generates a page with your &handheld; information. Some info about +your &kde;, &kpilot; and Pilot-Link version is included as well. The available +output formats are &HTML;, text or custom template. The conduit +output and in special, the debug output section of the output may help the +developers track down bugs. +</para> + + +<screenshot> +<screeninfo>The System Information Conduit Setup Dialog</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="conduit-sysinfo.png" +format="PNG"/></imageobject> +<textobject><phrase>System Information Conduit Setup</phrase></textobject> +<caption><para>System Information Conduit Setup</para></caption> +</mediaobject> +</screenshot> + +<para> +In the <guilabel>General</guilabel> page, you can set the output location and +format. +</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Output File</guilabel></term> +<listitem><para> +Write in the edit box or use the file picker to select the location and file +name of the output file where the &handheld; system information will be written. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Type of Output</guilabel></term> +<listitem><para> +Choose between <guilabel>HTML</guilabel>, <guilabel>Text file</guilabel> (plain +text), +or a selectable <guilabel>Custom template</guilabel>. To create a custom +template, you can +use the default template as a reference. +</para></listitem> +</varlistentry> + +</variablelist> + +<para> +In the <guilabel>Parts Included</guilabel> page, you can set which parts will be +included in the output, one by one, by checking or unchecking them in the +<guilabel>Output Type</guilabel> list. +</para> + +</sect2> + + +<sect2 id="todo-cond"> +<title>Todo Conduit Setup</title> + +<para> +This conduit will synchronize your &PalmPilot; To Do List application with +&korganizer; and &kontact;, or to an iCalendar file of your choice. +The configuration dialog looks and behaves exactly the same as the configuration +dialog for the <link linkend="vcal-cond">Calendar Conduit</link>. The only +difference is that instead of synchronizing the Calendar, you will be syncing +the To Do List. +</para> + +<screenshot> +<screeninfo>The Calendar Conduit Setup Dialog</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="conduit-vcal.png" format="PNG"/></imageobject> +<textobject><phrase>Calendar Conduit Setup</phrase></textobject> +<caption><para>Calendar Conduit Setup</para></caption> +</mediaobject> +</screenshot> + +</sect2> + +<sect2 id="mal-cond"> +<title>MAL (AvantGo) Conduit Setup</title> + +<para> +The MAL (&AvantGo;) Conduit synchronizes your &handheld; with the &AvantGo; +server. +This conduit is based on +<ulink url="http://jasonday.home.att.net/code/libmal/libmal.html">Jason Day's +libmal</ulink>. +The &AvantGo; server offers general content (news, guides, stock quotes, &etc;) +in a format that is suitable for reading in a &handheld;. To use this conduit, +you need to register to a service provider, for instance, +<ulink url="http://www.avantgo.com">AvantGo.com</ulink>, subscribe +the channels you select and install the &AvantGo; software on your &handheld;, +and configure the software on your handheld to find the MAL server. +</para> + +<para> +The installation software for the &handheld; client is usually only available +for &Microsoft; &Windows;, if you +do not have access to a windows computer, you can try installing the databases +available in the <ulink url="http://www.tomw.org/malsync/">MalSync +Homepage</ulink>, +with different versions, one for <trademark>PalmOS</trademark> 5 and other for +older <trademark>PalmOS</trademark>s. +</para> + +<para> +To configure the software on your handheld to find the MAL server, open the +AGConnect application in your &handheld;, click <guilabel>Settings...</guilabel> +and enter your MAL server address, the <guilabel>User Name</guilabel> and +<guilabel>Password</guilabel> you got while registering. The +&AvantGo; server address is +<userinput>sync.avantgo.com</userinput>, and its port is +<userinput>80</userinput>. On some installations, you should use the MobileLink +instead of the AGConnect application on your &handheld;. +</para> + +<screenshot> +<screeninfo>The MAL (AvantGo) Conduit Setup Dialog</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="conduit-mal.png" format="PNG"/></imageobject> +<textobject><phrase>MAL (AvantGo) Conduit Setup</phrase></textobject> +<caption><para>MAL (AvantGo) Conduit Setup</para></caption> +</mediaobject> +</screenshot> + +<para> +In the <guilabel>General</guilabel> page, you can set the synchronization +frequency options. It can be set for <guilabel>Every Sync</guilabel>, +<guilabel>Once per Hour</guilabel>, <guilabel>Once a Day</guilabel>, +<guilabel>Once a Week</guilabel> or <guilabel>Once a Month</guilabel>. +The conduit only runs when you hit &HotSync; on your &handheld;, so +<guilabel>Once per Hour</guilabel>, for instance, really means that +&kpilot; will only try to synchronize with the MAL servers if it is more than an +hour since the last MAL sync. +</para> + +<para> +The MAL conduit can work through a proxy server. In the +<guilabel>Proxy</guilabel> +page, you can set the proxy settings. +</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Proxy Type</guilabel></term> +<listitem><para> +If you connect the Internet directly, select <guilabel>No proxy</guilabel>, +requiring no further configuration. But if you use a <guilabel>HTTP +proxy</guilabel> +or a <guilabel>SOCKS proxy</guilabel>, select it, to enable the rest of the +dialog and to make the conduit use it to connect the MAL server. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Server Information</guilabel></term> +<listitem><para> +Write in the <guilabel>Server Name</guilabel> dropdown box the address of the +proxy server to use, in the form <userinput>foo.bar.com</userinput>, not +<userinput>http://foo.bar.com</userinput> or +<userinput>http://foo.bar.com:8080</userinput>. +</para> +<para> +Check the box <guilabel>Custom port:</guilabel> if your proxy uses a non +standard +port, and enter the correct port number. +</para> +<para> +In the <guilabel>No proxy for</guilabel> edit box, you may enter the list of MAL +servers that do not need the use of a proxy, separated by commas. For instance, +<userinput>localhost,lan</userinput>. +</para> +<para> +If your proxy require authentication, enter your <guilabel>User name</guilabel> +and <guilabel>Password</guilabel> in the respective edit boxes. +</para> +</listitem> +</varlistentry> + +</variablelist> + +<para>In the <guilabel>MAL Server</guilabel> page, you can set the MAL server +address and settings. Currently, you can only configure this settings using +the &handheld; MobileLink or AGConnect applications, so this page is +disabled.</para> + +</sect2> + +<sect2 id="popmail-cond"> +<title>Mail Conduit Setup</title> + +<para> +This conduit allows you to send mail using a transport. +The configuration of the Mail Conduit is fairly simple. +</para> +<screenshot> +<screeninfo>Setting up the Mail Conduit</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="conduit-popmail-kmail.png" +format="PNG"/></imageobject> +<textobject><phrase>The Mail Conduit Setup Dialog</phrase></textobject> +<caption><para>The Mail Conduit Conduit Setup Dialog</para></caption> +</mediaobject> +</screenshot> +<para> +There are two tabs in the setup dialog for the Mail Conduit, +one for Sending mail and one for the credits of the mail conduit. +</para> + +<para> +Depending on which send method you choose, +different fields will be activated in the remainder of the +tab, allowing you to enter the necessary information. +Currently, the only method available is <guilabel>Using KMail</guilabel>, +which has a very simple configuration. +</para> + +<para> +Your email address can be entered in the <guilabel>Email +Address:</guilabel> field. This is the email address that goes in the +<quote>From:</quote> line in outgoing mail. If you enter a file name in +the <guilabel>Signature File</guilabel> field then that file will be +appended to each outgoing mail as a signature. +</para> + +<para> +When sending mail through &kmail;, &kpilot; automatically places it in +your &kmail; outbox. &kmail; saves mail in the outbox until you request +that those pieces of mail are <emphasis>really</emphasis> sent. +</para> + +</sect2> +</sect1> + +</chapter>
\ No newline at end of file diff --git a/doc/kpilot/daemon-menu.png b/doc/kpilot/daemon-menu.png Binary files differnew file mode 100644 index 000000000..4e7018ddf --- /dev/null +++ b/doc/kpilot/daemon-menu.png diff --git a/doc/kpilot/db-app.png b/doc/kpilot/db-app.png Binary files differnew file mode 100644 index 000000000..f55842a2f --- /dev/null +++ b/doc/kpilot/db-app.png diff --git a/doc/kpilot/faq.docbook b/doc/kpilot/faq.docbook new file mode 100644 index 000000000..cbc9196e2 --- /dev/null +++ b/doc/kpilot/faq.docbook @@ -0,0 +1,386 @@ +<chapter id="faq"> +<title>&FAQ;</title> + +<sect1 id="faq-crash"> +<title>&kpilot; Startup Problems</title> + +<qandaset> + +<qandaentry> +<question> +<para> +What do I put after <option>--debug</option>? +</para> +</question> +<answer> +<para> +Nothing. Most versions of &kpilot; don't even have +a <option>--debug</option> option, and will complain if you use it. +For those versions that <emphasis>do</emphasis> have it, +use a value between 1 and 4, which will control the +amount of debugging printed (a little). +Using a value of 1 will print a fairly complete call trace +without the really-boring functions, while 4 will include every trivial +function in all of &kpilot;. +</para> + +</answer> +</qandaentry> + +<qandaentry id="faq-connection"> +<question> +<para> +&kpilot; says <errorname>Can't connect to pilot</errorname> +</para> +</question> +<answer> +<para> +This can have various causes. Check that: +<itemizedlist> +<listitem> +<para> + The pilot device (usually <filename + class="devicefile">/dev/pilot</filename>) exists and points to the + serial port the &PalmPilot; is actually connected to. +</para> +<para> + To link the &PalmPilot; device to the correct serial port, you can + either fill in + <filename + class="devicefile">/dev/ttyS<replaceable>n</replaceable></filename> + in the <guilabel>Pilot Device</guilabel> field in the <link + linkend="page-general">setup dialog</link> or (preferably) link + <filename class="devicefile">/dev/pilot</filename> to + <filename + class="devicefile">/dev/ttyS<replaceable>n</replaceable></filename> + with the following command (as <systemitem + class="username">root</systemitem>): + <userinput> + <command>ln</command> + <option>-s</option> + <parameter>/dev/ttyS<replaceable>n</replaceable></parameter> + <parameter>/dev/pilot</parameter></userinput> + Here <filename + class="devicefile">/dev/ttyS<replaceable>n</replaceable></filename> + is the name + of the serial port; replace <replaceable>n</replaceable> + with the correct number (usually 0 or 1). +</para> +</listitem> +<listitem> +<para> + Check that you have permission to read and write to the serial port. + The permissions for the serial port should be such that you can write to + it. This is most easily done by running the following (as root): + <userinput> + <command>chmod</command> + <option>666</option> + <parameter>/dev/ttyS<replaceable>n</replaceable></parameter> + </userinput> +</para> +</listitem> +<listitem> +<para> + Try starting the daemon by hand before starting &kpilot;. +</para> +</listitem> +<listitem> +<para> + (For &Linux-Mandrake; 7 systems) Check the system security level: + settings higher than 3 prevent some forms of inter-process + communication which are necessary for &kpilot; to + operate correctly. +</para> + +<para> + (<emphasis>&Linux-Mandrake; security information + courtesy of Jay Summett</emphasis>) + To set your +<!-- TM? --><acronym>MSEC</acronym> +<!-- TM? -->(Mandrake SECurity) + settings to not block the + &kpilot; socket (for connections to localhost) you can + login as root and + type + <userinput> + <command>/etc/security/msec/init.sh</command> + <option>3</option> + </userinput> + Which will set your +<!-- TM? --><acronym>MSEC</acronym> + level to 3 (regular security). + For more information about the various security levels, &etc;, see: + <ulink url="http://www.linux-mandrake.com/userguide/en/reference/017.html#157"> + the +<!-- TM? -->Mandrake +reference guide</ulink>. +</para> +</listitem> +</itemizedlist> +</para> +</answer> +</qandaentry> + +</qandaset> + +</sect1> + +<sect1 id="faq-database"> +<title>Database Questions</title> + +<para> +This section answers questions commonly asked about +particular databases and how they +interact with &kpilot;. +</para> + +<qandaset> + +<qandaentry> +<question> +<para> +Databases become corrupted after a sync, +what should I do? +</para> +</question> +<answer> +<para> +Certain databases (from third-party software manufacturers) +appear not to follow the standard database layout. +If you can find out what the creator id of the database is, +you can add it to either the +<guilabel>Backup Only:</guilabel> list or the +<guilabel>Skip</guilabel> list in the +<link linkend="page-backup">settings dialog</link>. +</para> + +<para> +The following table shows which databases should be skipped +or backed-up only: +<table id="dbskip"> +<title>Databases needing Special Treatment</title> +<tgroup cols="3"> +<thead> +<row><entry>Database</entry><entry>Creator ID</entry><entry>Action</entry></row> +</thead> +<tbody> +<row> + <entry>Launcher (the &PalmPilot;'s main menu)</entry> + <entry>lnch</entry> + <entry>Backup Only:</entry> +</row> +<row> + <entry>Arranger</entry> + <entry>Arng</entry> + <entry>Backup Only:</entry> +</row> +<row> + <entry>(unknown)</entry> + <entry>PmDB</entry> + <entry>Backup Only:</entry> +</row> +<row> + <entry>AvantGo</entry> + <entry>avgo</entry> + <entry>Skip (Mostly because there's no point in backing up the + news articles that AvantGo gives you)</entry> +</row> + +</tbody> +</tgroup> +</table> +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +Is there a conduit for &Netscape; <application>Calendar</application>? +</para> +</question> +<answer> +<para> +No, there isn't. +Neither are there plans to include support or write a +conduit for &Netscape; <application>Calendar</application>. +</para> +</answer> +</qandaentry> + + +</qandaset> + +</sect1> + +<sect1 id="faq-hotsync"> +<title> +Special HotSync Questions +</title> + +<para> +This section lists questions about HotSync methods that differ +from the <quote>usual</quote> direct serial link method. +</para> + +<qandaset> + +<qandaentry> +<question> +<para> +How do I do an infrared (<acronym>IR</acronym>) HotSync? +</para> +</question> +<answer> +<para> +First of all your &PalmPilot; has to actually support +<acronym>IR</acronym> HotSyncs. This can be achieved through various +means: &PalmOS; 3.3 and higher include support for it; there is an +<acronym>IR</acronym> enhancements package for older &PalmOS; versions; +<application>IrLink</application> from IsComplete apparently has the +same capabilities. Check out the <ulink +url="http://www.palmone.com/us/">PalmOne</ulink> web pages for more information. +</para> + +<para> +Assuming your &PalmPilot; now has <acronym>PC</acronym> HotSync support +and it is setup to do <acronym>IR</acronym> HotSyncs (in the HotSync +preferences on the &PalmPilot;), we can turn our attention to the +<acronym>PC</acronym> you will be synchronization with. It needs an +<acronym>IR</acronym> port. For laptops, this is trivial, desktop +<acronym>PCs</acronym> may require some extra hardware. +</para> + +<para> +Your &Linux; kernel will need to support <acronym>IR</acronym> and the <acronym>IRCOMM</acronym> protocol. +For stock +&RedHat; +systems, the following command should +setup <acronym>IR</acronym> support (as <systemitem class="username">root</systemitem>): +<screen width="40"> +<prompt># </prompt><userinput><command>modprobe</command> <option>ircomm</option></userinput> +</screen> + +Other distributions should follow the <filename>IR-HOWTO</filename>. +Once <acronym>IR</acronym> support in the kernel has been activated, +you need to make devices for the <acronym>IR</acronym> ports. +The <filename>IR-HOWTO</filename> suggests (as <systemitem class="username">root</systemitem>): +<screen width="40"> +<prompt># </prompt><userinput><command>mknod</command> +<option>/dev/ircomm0</option> <parameter>60</parameter> <parameter>64</parameter> </userinput> +<prompt># </prompt><userinput><command>chmod</command> +<option>666</option> <parameter>/dev/ircomm0</parameter></userinput> +</screen> +Next we need to start some daemons for <acronym>IR</acronym> services: +<screen width="40"> +<prompt># </prompt><userinput><command>irattach</command> +<option>/dev/ttyS<replaceable>n</replaceable></option></userinput> +<prompt># </prompt><userinput><command>irmanager</command> +<option>-d</option> <parameter>0</parameter></userinput> +</screen> +Here <filename class="devicefile">/dev/ttyS<replaceable>n</replaceable></filename> +is the serial port +the <acronym>IR</acronym> port is using. <replaceable>n</replaceable> could be 0, 1, or some other +number depending on your hardware setup. +Follow the instructions in the <filename>IR-HOWTO</filename> for assistance +(for desktop machines, it's usually a setting in the <acronym>BIOS</acronym>). +</para> + +<para> +Once you've gotten this far, just make <filename class="devicefile">/dev/pilot</filename> +point to <filename class="devicefile">/dev/ircomm0</filename> +and you're ready! +</para> + +<para> +The IR-HOWTO and other useful information on using IR may +be found at +<ulink url="http://mobilix.org/howtos.html">http://mobilix.org/howtos.html</ulink> +and +<ulink url="http://mobilix.org/software/irda/">http://mobilix.org/software/irda/</ulink>. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Can I do a &HotSync; with my (<acronym>USB</acronym>) +<!-- TM? -->&Handspring; &Visor;? +</para> +</question> +<answer> +<para> +Yes, you can. +I don't have definitive information, but postings on the +&kpilot; mailing-list have stated that you can point <filename class="devicefile">/dev/pilot</filename> +to the <acronym>USB</acronym> device and everything will work fine. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question><para>Is there any support for remote HotSyncs?</para> +</question> +<answer> +<para> +No, not yet. +Maybe later. +</para> +</answer> +</qandaentry> + +</qandaset> + +</sect1> + + +<sect1> +<title>&kpilot;'s &DCOP; interface</title> + +<qandaset> + +<qandaentry> +<question> +<para>What does &kpilot; use &DCOP; for?</para> +</question> +<answer><para> +The daemon and &kpilot; communicate using &DCOP; +for several purposes: logging messages, changing the &HotSync; +type, and exchanging configuration information. +</para></answer> +</qandaentry> + +<qandaentry><question> +<para>Which &DCOP; interfaces are there?</para></question> + +<answer><para> +The daemon has two important interfaces: +<interface>LogIface</interface> +and +<interface>KPilotDaemonIface +</interface>. +The <interface>LogIface</interface> +interface is used to record messages in the sync log +on the &handheld;, and is rarely used. +The <interface>KPilotDaemonIface</interface> +is the more important &DCOP; interface, +and is used to control the kind of &HotSync; that +&kpilot; will do. +</para></answer> +</qandaentry> + +<qandaentry><question><para> +How can I tell the daemon to perform a specific kind of &HotSync;?</para></question> +<answer><para> +There are three &DCOP; functions that control what kind +of &HotSync; +the daemon will do next: +<function></function> +<function></function> +</para></answer> +</qandaentry> +</qandaset> + +</sect1> + +</chapter> diff --git a/doc/kpilot/file-app.png b/doc/kpilot/file-app.png Binary files differnew file mode 100644 index 000000000..16e8d408e --- /dev/null +++ b/doc/kpilot/file-app.png diff --git a/doc/kpilot/index.docbook b/doc/kpilot/index.docbook new file mode 100644 index 000000000..e59ca9cd8 --- /dev/null +++ b/doc/kpilot/index.docbook @@ -0,0 +1,280 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd" [ +<!ENTITY kappname "&kpilot;"> +<!ENTITY kpilotver "4.4.6"> +<!ENTITY package "kdepim"> +<!ENTITY USB "<acronym>USB</acronym>"> +<!ENTITY PalmOS '<trademark class="registered">Palm OS</trademark>'> +<!ENTITY PalmOne '<trademark class="registered">PalmOne</trademark>'> +<!ENTITY Sony '<trademark class="registered">Sony</trademark>'> +<!ENTITY Clie "<productname><trademark>Clie</trademark></productname>"> +<!ENTITY FreeBSD '<trademark class="registered">FreeBSD</trademark>'> +<!ENTITY AvantGo '<trademark class="registered">AvantGo</trademark>'> +<!ENTITY handheld "handheld"> +<!ENTITY configuring-kpilot SYSTEM "configuration.docbook"> +<!ENTITY using-kpilot SYSTEM "usage.docbook"> +<!ENTITY synchronization SYSTEM "sync.docbook"> +<!ENTITY kpilot-faq SYSTEM "faq.docbook"> +<!ENTITY % English "INCLUDE" ><!-- Change language ONLY here --> +<!ENTITY % addindex "IGNORE"> +]> + +<!-- + From LW: http://www.palm.com/about/trademark.html According to this, + we have have overspecified some of the tradmarks... feel free to + adjust if you think this is the case. +--> + +<book lang="&language;"> + +<bookinfo> +<title>&kpilot; User's Guide</title> + +<authorgroup> +<author> + <firstname>Carlos</firstname> + <othername>Leonhard</othername> + <surname>Woelz</surname> + <affiliation> + <address><email>carloswoelz@imap-mail.com</email></address> + </affiliation> +</author> +<author> + <firstname>Adriaan</firstname> + <othername>de</othername> + <surname>Groot</surname> + <affiliation> + <address><email>groot@kde.org</email></address> + </affiliation> +</author> +<author> + <firstname>Dan</firstname> + <surname>Pilone</surname> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>1999</year> +<year>2000</year> +<year>2001</year> +<year>2002</year> +<year>2003</year> +<year>2004</year> +<holder>Adriaan de Groot</holder> +</copyright> + +<copyright> +<year>2004</year> +<year>2005</year> +<holder>Carlos Woelz</holder> +</copyright> + + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2004-06-27</date> +<releaseinfo>&kpilotver;</releaseinfo> + +<abstract> +<para> +&kpilot; &kpilotver; is the &kde; version of the Desktop &HotSync; software for +&PalmOne; handhelds, the &ThreeCom; &PalmPilot; and other &PalmOS; devices. +</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KPilot</keyword> +<keyword>kdepim</keyword> +<keyword>palm pilot</keyword> +<keyword>synchronization</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para> +&kpilot; &kpilotver; is an application that synchronizes your &PalmPilot; or +similar device (like the &Handspring; &Visor;, the &Sony; &Clie; or other +&PalmOS; devices) with your &kde; desktop, much like the Palm Desktop &HotSync; +software does for &Windows;. &kpilot; can back-up, restore, and &HotSync; your +&PalmPilot;. It can synchronize the built-in applications with their &kde; +counterparts. It also features additional conduits for third-party software. +</para> + +<para> +There is a web page for &kpilot;: the <ulink +url="http://www.kpilot.org/">Official &kpilot; Home Page</ulink>. The <ulink +url="http://pim.kde.org/">KDE-PIM website</ulink> also offers useful information +on the subject of <acronym>PIM</acronym> in general. &kpilot; shares the +kdepim-users mailing list, <email>kdepim-users@kde.org</email>. See <ulink +url="http://www.kde.org/mailinglists"> the mailing lists page</ulink> for more +information on subscribing and unsubscribing from the list. +</para> + +<!-- +<para> +A word about version numbers: &kpilot; 4.5.x is current and still unstable as of +August 2005. It does not work with KDE versions lower than 3.2. +</para> +--> + +<sect1 id="trademarks"> +<title>Trademarks</title> +<para> +&kpilot; describes synchronization operations +with &PalmOS; devices, and it uses the word &HotSync; +to name those synchronization operations, +while recognizing that &HotSync; is a trademark of +Palm, Inc. Holders of other trademarks, such as +&Handspring; &Visor;, &Sony; &Clie;, and +the Palm, Inc. trademarks &PalmPilot; and +<productname><trademark>Zire</trademark></productname> +are recognized as well. +</para> +</sect1> + +</chapter> + +<chapter id="overview"> +<title>Overview of &kpilot;</title> + +<para> +&kpilot; consists of two parts: the &kpilot; daemon, which sits +in the system tray and handles the actual communication with +the &handheld;, and the normal &kpilot; program, which lets +you configure the daemon and view the databases on your +&handheld;. In normal operation, you will not need to use &kpilot; +itself very much, since the daemon handles communication unobtrusively +and synchronizes your data to &kde; applications like &korganizer; +and &knotes;. &kpilot; is integrated into &kontact; as well. +</para> + +<para> +It is vital to configure &kpilot; before use. At the very least, +you need to tell it which hardware device to use to communicate with +your &handheld;. +Configuration settings are described at length in +the <link linkend="configure">section on configuring &kpilot;</link>. +For the impatient, the <link linkend="configwizard">configuration wizard</link> +can set up most things for you. +</para> + +<para> +Once &kpilot; is configured, you should make a <link +linkend="backup">backup</link> of your &handheld; first. That is to be on the +safe side. Once that is done, you can just leave the &kpilot; daemon running in +the system tray, and all you need to do is press the &HotSync; button, and +changes in the &handheld; data and the &kde; applications will be <link +linkend="synchronization">synchronized</link>, so that the information matches +again on both the &handheld; and the desktop. +</para> + +<para> +If you want to <link linkend="page-viewers">examine</link> the +data stored on your &handheld;, the built in <link +linkend="page-viewers">viewers</link> can be used. This allows you to view +memos, addresses, &etc;. There is a generic hexadecimal database viewer for +advanced use. +</para> + +<para> +Finally, &kpilot; can be used to <link linkend="installer-app">install</link> +new programs and databases on your &handheld;. +</para> + +<!-- +FIXME: Old Warnings +<caution> +<title>Changes in &kpilotver;</title> +<para> +The expressiveness of the <guilabel>No Backup</guilabel> configuration +item, which prevents specific databases from being backed up (for space, speed, +or stability reasons), has been extended. +In particular, the old format listed only +creator values, while the new format can list wildcard database names +as well as creator values. +The value set in the configuration dialog will be automatically adjusted to +the new format. +</para> +<para> +In &kpilot; &kpilotver;, the way conduits are programmed changed, +and you will need to use newly compiled conduits. If there are +old conduits on your system, &kpilot; will prompt you to remove them. +</para> +<para> +Please take the time to review all of the configuration settings. +</para> +</caution> +--> +</chapter> + + +&configuring-kpilot; +&using-kpilot; +&synchronization; +&kpilot-faq; + + +<chapter id="credits"> + +<title>Credits and License</title> + +<para> +&kpilot; +Program copyright 1998-2000 by &Dan.Pilone; +&Dan.Pilone.mail; +</para> +<para> +Contributors: +<itemizedlist> +<listitem><para>Adriaan de Groot <email>groot@kde.org</email></para> +</listitem> +<listitem><para>&Preston.Brown; <email>pbrown@redhat.com</email></para> +</listitem> +<listitem><para>VCal and Todo Conduits by: Herwin Jan Steehouwer, +Kenneth Albanowski, &Michael.Kropfberger; +</para></listitem> +<listitem><para>Popmail Conduit overhaul: Marko Grönroos +</para></listitem> +<listitem><para>&kaddressbook; Conduit: Greg Stern +</para></listitem> +<listitem><para>Patches by: +Jörn Ahrens, +Robert Ambrose, +Jörg Habenicht, +Philipp Hullmann, +Dag Nygren, +Scott Presnell, +Heiko Purnhagen, +Chuck Robey +and +Jay Summet +</para></listitem> +</itemizedlist> +</para> + +<para> +Documentation copyright 2000,2001 Adriaan de Groot <email>groot@kde.org</email>. +Documentation copyright 2004,2005 Carlos Leonhard Woelz +<email>carloswoelz@imap-mail.com</email> +</para> + +<!-- TRANS:CREDITS_FOR_TRANSLATORS --> +&underFDL; +&underGPL; +</chapter> + +&documentation.index; +</book> +<!-- +Local Variables: +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +End: +--> + diff --git a/doc/kpilot/main-app.png b/doc/kpilot/main-app.png Binary files differnew file mode 100644 index 000000000..8eb613b1e --- /dev/null +++ b/doc/kpilot/main-app.png diff --git a/doc/kpilot/memo-app.png b/doc/kpilot/memo-app.png Binary files differnew file mode 100644 index 000000000..8c0b4a6d8 --- /dev/null +++ b/doc/kpilot/memo-app.png diff --git a/doc/kpilot/setup-address.png b/doc/kpilot/setup-address.png Binary files differnew file mode 100644 index 000000000..958225c42 --- /dev/null +++ b/doc/kpilot/setup-address.png diff --git a/doc/kpilot/setup-conduit.png b/doc/kpilot/setup-conduit.png Binary files differnew file mode 100644 index 000000000..3c4fed21e --- /dev/null +++ b/doc/kpilot/setup-conduit.png diff --git a/doc/kpilot/setup-dbspecial.png b/doc/kpilot/setup-dbspecial.png Binary files differnew file mode 100644 index 000000000..9ea5a6acf --- /dev/null +++ b/doc/kpilot/setup-dbspecial.png diff --git a/doc/kpilot/setup-general.png b/doc/kpilot/setup-general.png Binary files differnew file mode 100644 index 000000000..e79d71e4a --- /dev/null +++ b/doc/kpilot/setup-general.png diff --git a/doc/kpilot/setup-hotsync.png b/doc/kpilot/setup-hotsync.png Binary files differnew file mode 100644 index 000000000..75b535813 --- /dev/null +++ b/doc/kpilot/setup-hotsync.png diff --git a/doc/kpilot/setup-items.png b/doc/kpilot/setup-items.png Binary files differnew file mode 100644 index 000000000..f730a9c13 --- /dev/null +++ b/doc/kpilot/setup-items.png diff --git a/doc/kpilot/setup-startup-exit.png b/doc/kpilot/setup-startup-exit.png Binary files differnew file mode 100644 index 000000000..0d8b8a76f --- /dev/null +++ b/doc/kpilot/setup-startup-exit.png diff --git a/doc/kpilot/setup-tabs.png b/doc/kpilot/setup-tabs.png Binary files differnew file mode 100644 index 000000000..87e6ef2de --- /dev/null +++ b/doc/kpilot/setup-tabs.png diff --git a/doc/kpilot/setup-viewer.png b/doc/kpilot/setup-viewer.png Binary files differnew file mode 100644 index 000000000..96bee4a54 --- /dev/null +++ b/doc/kpilot/setup-viewer.png diff --git a/doc/kpilot/sidebar.png b/doc/kpilot/sidebar.png Binary files differnew file mode 100644 index 000000000..6c178edff --- /dev/null +++ b/doc/kpilot/sidebar.png diff --git a/doc/kpilot/sync.docbook b/doc/kpilot/sync.docbook new file mode 100644 index 000000000..5fba145cb --- /dev/null +++ b/doc/kpilot/sync.docbook @@ -0,0 +1,450 @@ +<chapter id="synchronization"> +<title>Syncing your &handheld; with a PC</title> + +<para> +This chapter describes the synchronization process +that &kpilot; uses, focusing on the &kpilot; daemon functionality. +You may sync your &handheld; using the <link linkend="builtin">internal +viewers</link> and / or <link linkend="conduits">conduits</link>, depending +on your personal preferences. Conduits allow external applications to interface +with the data on your &handheld;. +</para> + +<para> +It is a good idea to make a <link linkend="backup">backup</link> +of your &handheld; regularly. Other than making backups, it should rarely be +necessary to do anything other than drop your &handheld; on the cradle and press +the &HotSync; button. The &kpilot; daemon icon in the system tray will flash +indicating that a sync is under way. +</para> + + +<screenshot> +<screeninfo>&kpilot; Daemon Pop-Up Menu</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="daemon-menu.png" format="PNG"/></imageobject> +<textobject><phrase>&kpilot; daemon popup menu</phrase></textobject> +<caption><para>&kpilot; daemon popup menu</para></caption> +</mediaobject> +</screenshot> + + +<para> +To which type of sync &kpilot; will perform next, you can use the main +application +<link linkend="menu-file"> +<menuchoice> +<guimenu>File</guimenu> +</menuchoice> +menu</link>, +or right click the &kpilot; daemon icon located in the system tray, +and select one of the menu items under the +<menuchoice> +<guisubmenu>Next Sync</guisubmenu> +</menuchoice> +sub menu. +<tip><para> +If you hover over the &kpilot; daemon icon, a tooltip will appear showing you +what the type of sync &kpilot; will perform next. +</para></tip> + +</para> + + + +<para> +In short, the sync types are: +</para> + +<itemizedlist> + +<listitem><para> +<guilabel>HotSync (once)</guilabel>: this option offers +a nice balance between speed and data safety. +</para></listitem> + +<listitem><para> +<guilabel>FastSync (once)</guilabel>: only sync those +databases that have conduits. +</para></listitem> + +<listitem><para> +<guilabel>FullSync (once)</guilabel>: the safest option, but +takes the longest time to complete. +</para></listitem> + +<listitem><para> +<guilabel>Backup (once)</guilabel>: copy all the data from the &handheld; to the +<acronym>PC</acronym>. +</para></listitem> + +<listitem><para> +<guilabel>Restore from Backup (once)</guilabel>: copy the data from a previous backup from the PC to the +&handheld;, erasing the data previously held there. + +<warning><para> +Use the restore functionality with care, as you can lose all the new +data entered on the &handheld; since the last backup. +</para></warning> +</para> +</listitem> + +<listitem> +<para> +<guilabel>Copy Handheld to PC (once)</guilabel>: run all conduits and +sync all databases, but instead of merging the information from both sources, +just copy the handheld data to the PC. +<warning><para>Use with care, as this option erases the changes +you made in your PC since the last sync.</para></warning> +</para> +</listitem> + +<listitem> +<para> +<guilabel>Copy PC to Handheld (once)</guilabel>: run all conduits and +sync all databases, but instead of merging the information from both sources, +just copy the PC data to the handheld. +<warning><para>Use with care, as this option erases the changes +you made in your handheld since the last sync.</para></warning> +</para> +</listitem> + +</itemizedlist> + + +<para> +Alternatively, you can change the default syncing behavior of &kpilot; by +choosing the most suitable option in the <link linkend="page-hotsync">&HotSync; +configure dialog</link>. + +<note><para> +To configure the conduits or the sync process, you do not need to open the main +&kpilot; application, as the +<menuchoice> +<guimenuitem>Configure KPilot...</guimenuitem> +</menuchoice> +menu item is available on the &kpilot; daemon popup menu as well. +</para></note> + +</para> + +<sect1 id="backup"> +<title>Backing up your &handheld; data</title> + +<para> +On every backup, &kpilot; stores a copy of all your &handheld; data under the +<filename class="directory">$KDEHOME/share/apps/kpilot/DBBackup/User Name/</filename> +folder, allowing you to restore that copy later, if needed. The +<filename class="directory">$KDEHOME</filename> environment variable +(typically <filename class="directory">/home/Login Name/.kde/</filename>) +points to the folder that contains your configuration and data for the &kde; +applications.</para> + +<para> +It is a good idea to backup your data often. To perform a backup, you can click +the +<menuchoice> +<guisubmenu>Next Sync</guisubmenu> +<guimenuitem>Backup</guimenuitem> +</menuchoice> +on the &kpilot; daemon icon popup menu or the +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Backup</guimenuitem> +</menuchoice> +menu item on the main &kpilot; application menu in order +to make the next sync a backup. Then, just press the &HotSync; button. +</para> + +</sect1> + +<sect1 id="restore"> +<title>Restoring Your &handheld; Data</title> + +<para> +The restore operation consist of transferring all the data previously saved on +the <acronym>PC</acronym> to the &handheld;, effectively erasing all the new +data held by the device by returning it to a previous state. +<warning><para> +Use the restore functionality with care, as you can lose all the new +data entered on the &handheld; since the last backup. +</para></warning> +</para> + +<para> +The data saved on the last backup is located on the <filename class="directory">$KDEHOME/share/apps/kpilot/DBBackup/User Name/</filename> +folder. The <filename class="directory">$KDEHOME</filename> environment variable +(typically <filename class="directory">/home/Login Name/.kde/</filename>) +points to the folder that contains your configuration and data for the &kde; +applications.</para> + +<para> +The most common use for the restore functionality is to recover from a hardware +or software failure on the device. +The restore function can be accessed from the +main &kpilot; application, and from the &kpilot; daemon. be careful, as +restoring the data is not a common operation. In order +to restore the data at the next sync, click the +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Restore</guimenuitem> +</menuchoice> +menu item, then press the &HotSync; button. +</para> + +</sect1> + + +<sect1 id="sync-s"> +<title>Selecting the Synchronization Type</title> + +<para> +There are three ways to sync your &handheld;, <guilabel>HotSync</guilabel>, +<guilabel>FastSync</guilabel> or <guilabel>FullSync</guilabel>. +</para> + +<para> +When you press the &HotSync; button on your &handheld;, &kpilot;'s will run the +default sync operation (usually a <guilabel>HotSync</guilabel>). You can select +the default sync operation in the <link linkend="page-hotsync">&HotSync; +configure dialog</link>. Alternatively, you can click one of the sync options on +the main &kpilot; application +<menuchoice> +<guimenu>File</guimenu> +</menuchoice> +menu or on the &kpilot; daemon popup +<menuchoice> +<guisubmenu>Next Sync</guisubmenu> +</menuchoice> +submenu. + +<important><para> +Using the <link linkend="page-hotsync">&HotSync; configure dialog</link> +is the only way to change the default sync operation. +The main &kpilot; application +<menuchoice> +<guimenu>File</guimenu> +</menuchoice> +menu items or the &kpilot; daemon popup +<menuchoice> +<guisubmenu>Next Sync</guisubmenu> +</menuchoice> +submenu items change only the type of sync that will be performed <emphasis>next</emphasis>. +</para></important> +</para> + +<screenshot> +<screeninfo>&kpilot; Daemon Pop-Up Menu</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="daemon-menu.png" format="PNG"/></imageobject> +<textobject><phrase>&kpilot; daemon popup menu</phrase></textobject> +<caption><para>&kpilot; daemon popup menu</para></caption> +</mediaobject> +</screenshot> + + +<para> +For more information on the sync types, please refer to the descriptions +available in <xref linkend="page-hotsync" />. +</para> + + +</sect1> + +<sect1 id="conduits"> +<title>Syncing your &handheld; Data Using Conduits</title> + +<para> +Conduits are programs that interface your &handheld; data with +<acronym>PC</acronym> applications or sync your &handheld; data with files +that can be used by <acronym>PC</acronym> applications. +</para> + +<para> +Conduits can be set up by selecting +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure KPilot...</guimenuitem> +</menuchoice>, or using the daemon pop up menu and clicking the +<guimenuitem>Configure KPilot...</guimenuitem> +menu item. +</para> + +<screenshot> +<screeninfo>&kpilot; Daemon Pop-Up Menu</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="daemon-menu.png" format="PNG"/></imageobject> +<textobject><phrase>&kpilot; daemon popup menu</phrase></textobject> +<caption><para>&kpilot; daemon popup menu</para></caption> +</mediaobject> +</screenshot> + +<para> +The <guilabel>Conduits</guilabel> tree in the configuration dialog +collects all the installed conduits available. +The conduits can be enabled and disabled +by clicking on the check box to the left of the conduit's name. +Conduits can have an extensive configuration of +their own, and may be supplied by third parties. +Most of the conduits require some initial configuration, so it is strongly +recommended to check the +<link linkend="config-conduits">section detailing the default conduits +configuration</link> before using them. +</para> + + +<para> +The default conduits are the following: +</para> + + +<variablelist> + +<varlistentry> +<term><guilabel>KNotes / Memos</guilabel></term> +<listitem><para> +Synchronizes the Memo Pad application with &knotes;. + +<important><para> +The conduit only synchronizes the Memo Pad data if &knotes; is running. If you +want to enable this functionality, please remember to start &knotes; first, or +check if it is already running (tip: look for the &knotes; icon in the system tray). +</para></important> + +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><guilabel>Notepad</guilabel></term> +<listitem> +<para> +Exports the free hand notes of the &handheld;'s Notepad application as pictures +to the PC. +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term><guilabel>Time Synchronization</guilabel></term> +<listitem><para> +Sets the &handheld;'s time to that of the desktop machine. +Useful for keeping the clock of the &handheld; accurate. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Calendar (KOrganizer)</guilabel></term> +<listitem><para> +Synchronizes the Datebook application with &korganizer; or with a iCalendar file of +your choice. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Palm DOC</guilabel></term> +<listitem><para> +Automatically converts, installs and sync text files in the &PalmPilot; +DOC format, so you can read the text files with most DOC-capable +applications on the &handheld;. There are many free or open source Palm +DOC readers, and some Palm DOC editors for your handheld.</para> +<para> +Any plain text file can be easily converted. For instance, you can download and +convert the public domain books provided by the <ulink url="http://www.gutenberg.net"> +Gutenberg Project</ulink> and read them in your &handheld;. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Addressbook</guilabel></term> +<listitem><para> +Synchronizes the Address application with &kaddressbook; or with a vCard file of +your choice. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>System Information</guilabel></term> +<listitem><para> +Writes information about your &handheld;, (such as OS version, +RAM available, and the list of databases) to a file. Useful mostly for +debugging purposes. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>ToDo's (KOrganizer)</guilabel></term> +<listitem><para> +Synchronizes the Todo list application with &korganizer; or with a iCalendar file of +your choice. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>MAL (AvantGo) Conduit</guilabel></term> +<listitem><para> +Synchronizes your &handheld; with the &AvantGo; server. The &AvantGo; server +offers general content (news, guides, stock quotes, &etc;) in a format that is +suitable for reading in a &handheld;. To use this conduit, you need to register, subscribe +the channels you select and install the &AvantGo; software on your &handheld;. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><guilabel>Mail</guilabel></term> +<listitem><para> +Sends mail written on the &handheld; through &kmail;. +There is no provision for receiving mail, however. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Perl</guilabel></term> +<term><guilabel>Python</guilabel></term> +<term><guilabel>NULL</guilabel></term> +<listitem><para> +These conduits are intended as a programming demonstration, +and serve no practical purpose during a &HotSync;. +They are not normally listed, but you may see them on some systems. +</para></listitem> +</varlistentry> + +</variablelist> + +<screenshot> +<screeninfo>The Conduit Setup Dialog</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="setup-conduit.png" format="PNG"/></imageobject> +<textobject><phrase>The Conduit Setup Dialog</phrase></textobject> +<caption><para>The Conduit Setup Dialog</para></caption> +</mediaobject> +</screenshot> + + +</sect1> + +<sect1 id="conflicts"> +<title>Resolving Conflicts</title> + +<para> +Data records can be changed both on the &handheld; and +on the <acronym>PC</acronym>. If one record has incompatible changes +in both the &handheld; and the <acronym>PC</acronym>, (such as +changing a phone number in different ways on both sides), +the conflicting change needs to be resolved so +that both the &handheld; and the <acronym>PC</acronym> are in sync again. +</para> + +<para> +A popup dialog may appear, asking you how to resolve the +conflict, or you may have a general rule to automatically handle these +conflicts (depending on your <link linkend="page-hotsync">conflict resolution +choice</link>). Note that you can define different resolution choices +for different conduits in the <link linkend="config-conduits">conduits +configuration dialog</link>. +</para> + +</sect1> +</chapter> diff --git a/doc/kpilot/todo-app.png b/doc/kpilot/todo-app.png Binary files differnew file mode 100644 index 000000000..7b541850e --- /dev/null +++ b/doc/kpilot/todo-app.png diff --git a/doc/kpilot/toolbar_backup.png b/doc/kpilot/toolbar_backup.png Binary files differnew file mode 100644 index 000000000..d1ab921d3 --- /dev/null +++ b/doc/kpilot/toolbar_backup.png diff --git a/doc/kpilot/toolbar_hotsync.png b/doc/kpilot/toolbar_hotsync.png Binary files differnew file mode 100644 index 000000000..11eceb43b --- /dev/null +++ b/doc/kpilot/toolbar_hotsync.png diff --git a/doc/kpilot/usage.docbook b/doc/kpilot/usage.docbook new file mode 100644 index 000000000..803da4ba5 --- /dev/null +++ b/doc/kpilot/usage.docbook @@ -0,0 +1,648 @@ +<chapter id="using-kpilot"> +<title>Using &kpilot; Data Viewers and Main Window Interface</title> + +<para> +This chapter describes the usage of &kpilot;'s main window; as a viewer +application for data on the &handheld;, and its menu structure. +The main window of &kpilot; also contains +the &HotSync;-log, which can be useful when +debugging problems. +</para> + +<para> +&kpilot; starts up with a splash screen, and then switches to showing the +&HotSync;-log, as shown <link linkend="main-app">here</link>. +</para> + +<sect1 id="main"> +<title>The Main Window</title> + +<screenshot id="main-app"> +<screeninfo>&kpilot; Main Window</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="main-app.png" format="PNG"/></imageobject> +<textobject><phrase>The Main Window</phrase></textobject> +<caption><para>The Main Window</para></caption> +</mediaobject> +</screenshot> + +<para> +The main window contains the application menu, which we will deal with here. +</para> + +<para> +The <guimenu>file</guimenu> menu contains the synchronization menu items. Note +that these items do not start the sync process, they only select what the new +sync will be. To really start it, you must press the HotSync button on your +&PalmPilot;'s cradle (or on the &handheld; itself, when there is no cradle). +</para> +<note> +<para> +It is not possible to cancel a sync operation once the request has been made. +</para> +</note> +<para> +For more information regarding the synchronization functionality, please check the +<link linkend="synchronization">Synchronization Chapter</link> of this handbook, +where you can find detailed descriptions of the synchronization methods +and options offered by &kpilot;. +</para> + +<variablelist id="menu-file"> + +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>HotSync</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Make the next sync a &HotSync;. For more information, please check the +<link linkend="sync-s"> Syncing your &handheld; data</link> section of this +handbook. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>FastSync</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +(not available with all installations) +Make the next sync a FastSync. For more information, please check the +<link linkend="sync-s">Syncing your &handheld; data</link> section of this +handbook. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>FullSync</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +(not available with all installations) +Make the next sync a FullSync. For more information, please check the +<link linkend="sync-s"> Syncing your &handheld; data</link> section of this +handbook. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Backup</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Make the next sync a full backup of your &PalmPilot; data. This action can take +several minutes. For more information, please check the +<link linkend="backup"> Backing up your &handheld; data</link> section of this +handbook. +</para> +<tip> +<para> +The first thing you should do after starting &kpilot; for +the first time is make a full backup. +</para> +</tip> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Restore</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This copies all the data from a previous backup on your +<acronym>PC</acronym> to your &PalmPilot;, +replacing whatever data was there. +Use this if your &PalmPilot; suffers some from software or hardware failure +(or is replaced by a new one). For more information, please check the +<link linkend="restore"> Restoring your &handheld; data</link> section of this +handbook. +</para> +<warning> +<para> +Doing a restore will erase all data on the &PalmPilot; +before restoring the information from your +<acronym>PC</acronym>!</para> +</warning> +</listitem> +</varlistentry> + + +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Copy Handheld to PC</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This runs all conduits and syncs all databases, but instead of merging the +information from both sources, it will copy the handheld data to the PC. +<emphasis>Use with care, as this option erases the changes +you made in your PC since the last sync</emphasis>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Copy PC to Handheld</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This runs all conduits and syncs all databases, but instead of merging the +information from both sources, it will copy the PC data to the handheld. +<emphasis>Use with care, as this option erases the changes +you made in your handheld since the last sync</emphasis>.</para> +</listitem> +</varlistentry> + + +<!-- +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>List Only</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +The next sync will only list the databases on your &handheld;, no exchange of +data will be performed. +</para> +</listitem> +</varlistentry> +--> + +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Quit</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Quits &kpilot;, closing the main window and stopping the +daemon if that +<link linkend="stopdaemononexit">configuration option</link> +is enabled. +</para> +</listitem> +</varlistentry> +</variablelist> + + +<para> +The <guimenu>Settings</guimenu> menu allows you to configure &kpilot; main +interface and fine-tune the synchronization process with the &handheld;. +</para> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Show Statusbar</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Click this menu item to toggle &kpilot;'s status bar on and off, or in other +words, to show it if hidden, or to hide it if shown. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Show Toolbar</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Click this menu item to toggle &kpilot;'s toolbar on and off, or in other +words, to show it if hidden, or to hide it if shown. +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Shortcuts...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Displays &kpilot;'s shortcut configuration dialog, allowing you change or create +key bindings, which are associations between actions (for example, opening +&kpilot;'s configuration dialog) and keys or key combinations (for instance, +Ctrl + Shift + a). +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Toolbars...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Displays &kpilot;'s toolbar configuration dialog. This dialog lists all actions +available for use on the toolbar, and the actions currently displayed, allowing +you to add or remove actions, and move the actions which already are on the +toolbar. +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure KPilot...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Displays &kpilot;'s configuration dialog, allowing you to match your hardware +with the configuration, so that &kpilot; can talk with your &handheld;, to +configure the way &kpilot; synchronizes your &PalmPilot; with your +desktop applications (through conduits) and the way it shows the data from your &PalmPilot; in the +<link linkend="builtin">built-in viewers</link>. The <link linkend="configure"> +Configuring &kpilot;</link> chapter of this handbook offers detailed information +about these configuration options. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configuration Wizard...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Displays &kpilot;'s configuration wizard dialog. The +<link linkend="configwizard">configuration wizard</link> helps you to set up +&kpilot; to communicate with the &PalmPilot; and to configure the conduits as +a group. It's a great start for new users, and you can always fine-tune your +preferences later, using the <link linkend="configure">configure +dialog</link>. +</para> +</listitem> +</varlistentry> + + +</variablelist> + + +</sect1> + +<sect1 id="builtin"> +<title> +Built-in Applications +</title> + +<para> +To select one of the Built in applications, just click its icon on &kpilot;'s +sidebar. +</para> + +<screenshot> +<screeninfo>KPilot's Sidebar</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="sidebar.png" format="PNG"/></imageobject> +<textobject><phrase>KPilot's Sidebar</phrase></textobject> +<caption><para>KPilot's Sidebar</para></caption> +</mediaobject> +</screenshot> + + +<para> +Selecting one of the built-in applications +will cause that application to appear in &kpilot;'s main +window. +You may use the viewer applications to edit the information, by enabling +this option in the <link linkend="page-viewers">database viewer's +configuration dialog</link>. The ability to view and edit private records is +configurable too.</para> + +<para> +Any changes you make to the &PalmPilot; databases with +the built-in applications (such as deleting a memo) +do not take effect on the &PalmPilot; until the next HotSync. +</para> + +<important><para> +If the <guilabel>Make internal viewers editable</guilabel> option is +not enabled, the changes in the viewers are not synchronized with your +&handheld;, and will be lost. In recent versions of &kpilot; it is not possible +enable this option, and therefore, to edit the databases with the viewers. +</para></important> + +<sect2 id="todo-app"> + +<title>The Todo Viewer</title> + +<para> +The todo application allows you to view the tasks from your &PalmPilot;, +add new tasks and edit or delete existing ones. The changes you made +are applied to the &handheld; the next time you &HotSync;. +</para> + +<screenshot> +<screeninfo>Todo Viewer Application</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="todo-app.png" format="PNG"/></imageobject> +<textobject><phrase>The Todo Viewer Application</phrase></textobject> +<caption><para>The Todo Viewer Application</para></caption> +</mediaobject> +</screenshot> + +<para> +The todo application has a drop down box +for the memo categories defined in the &PalmPilot;. +In the screenshot, category <quote>All</quote> is selected. +Underneath the drop down box is a list of todo entries, with a check box +indicating if they are completed or not. You can click the check box to toggle +the todo item between completed and not completed status. Clicking on one of the +todo items in the list will display its details in the text box labelled +<guilabel>Todo info:</guilabel> to the right. +</para> + +<para> +If you have the <guilabel>Make internal viewers editable</guilabel> option +enabled in the <link linkend="page-viewers">viewers configuration page</link> you +can use the buttons <guibutton>Edit Record...</guibutton>, +<guibutton>New Record...</guibutton> and <guibutton>Delete Record</guibutton> +to edit the todo data from your &handheld;, and sync the data in the next +&HotSync;.</para> + +<!-- +<note><para> +If you create new todo and decide that +you do not want to have it on the &PalmPilot; +you must perform a &HotSync; (copying the todo +to the &PalmPilot;) and then delete the todo record +from the &PalmPilot; or the viewer, and &HotSync; again. It is not possible to +delete newly-added records from the built-in applications. +</para></note> +--> + +<para> +The <guibutton>Edit Record...</guibutton> button opens a dialog where you can +edit the details of the currently selected todo item, including description, +priority and end date. Click the <guibutton>New Record...</guibutton> button to +open the same dialog, but instead of editing the current selected record, a new +todo will be added to the list. And finally, click the +<guibutton>Delete Record</guibutton> button to remove the selected todo record +from the list. +</para> + +</sect2> + +<sect2 id="address-app"> +<title>The Address Viewer</title> +<para> +The address viewer lets you view, create, delete and edit addresses +from the &PalmPilot;, and synchronize changes back. The addresses can be +sorted and viewed in the <guilabel>"Last, first"</guilabel> or <guilabel>"Company, +last"</guilabel> format, depending on your +<link linkend="page-viewers">viewers configuration.</link> +</para> + +<screenshot> +<screeninfo>The Address Viewer Application</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="address-app.png" format="PNG"/></imageobject> +<textobject><phrase>The Address Viewer Application</phrase></textobject> +<caption><para>The Address Viewer Application</para></caption> +</mediaobject> +</screenshot> + + +<para> +The address application resembles the todo application; +the drop down box, buttons, list and text area function exactly +the same, allowing you to select, view and edit an address +as on the &PalmPilot;. +</para> + +<para> +The <guibutton>Edit Record...</guibutton> dialog allows you to edit the +<guilabel>Last Name</guilabel>, <guilabel>First Name</guilabel>, +<guilabel>Company</guilabel>, &etc; fields, just as if you where using your +&handheld;. Click the <guibutton>New Record...</guibutton> button to +open the same dialog, but instead of editing the current selected record, a new +address will be added to the list. Click the +<guibutton>Delete Record</guibutton> button to remove the selected address +from the list. + +<!-- +<note><para> +If you create new address and decide that +you do not want to have it on the &PalmPilot; +you must perform a &HotSync; (copying the address +to the &PalmPilot;) and then delete the address record +from the &PalmPilot; or the viewer, and &HotSync; again. It is not possible to +delete newly-added records from the built-in applications. +</para></note> +--> + +</para> +</sect2> + + +<sect2 id="memo-app"> + +<title>The Memo Viewer</title> + +<para> +The memo application allows you to view the memos on your &PalmPilot;, +export them to text files, import new ones to be installed the next +time you &HotSync;, or edit existing ones. +</para> + +<screenshot> +<screeninfo>Memo Viewer Application</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="memo-app.png" format="PNG"/></imageobject> +<textobject><phrase>The Memo Viewer Application</phrase></textobject> +<caption><para>The Memo Viewer Application</para></caption> +</mediaobject> +</screenshot> + +<para> +The memo application has a drop down box +for the memo categories defined in the &PalmPilot;. +Here category <quote>All</quote> is selected. +Underneath the drop down box is a list of memo titles. +These are the first lines of the memos, just like +in the &PalmPilot; memo application. +Clicking on one of the memo titles in the list +box will display it in the text box labelled +<guilabel>Memo Text:</guilabel> to the right. +</para> + +<para> +When a memo is selected, you can use the buttons +<guibutton>Export Memo...</guibutton> and +<guibutton>Delete Memo</guibutton> +to export the selected memo to a file +or to delete the selected memo. +Exporting a memo requires +you to give a filename; the memo +is written to that file. +Take care not to overwrite existing files with this action. +Deleting a memo does not affect the &PalmPilot; +until the next &HotSync;. +</para> + +<para> +The +<guibutton>Import Memo...</guibutton> +button allows you to read a text file and +add it — as a memo — to the &PalmPilot;. +Importing a memo does not take effect until +the next &HotSync;. + +<!-- +<note><para> +If you import a memo and decide that +you do not want to have it on the &PalmPilot; +you must perform a &HotSync; (copying the memo +to the &PalmPilot;) and then delete the memo record +from the &PalmPilot; or the viewer, and &HotSync; again. It is not possible to +delete newly-added records from the built-in applications. +</para></note> +--> + +</para> + + +</sect2> + +<sect2 id="db-app"> +<title>The Generic DB Viewer</title> + +<para> +In short, databases are all files stored in your &handheld;. A database +can be either a record database, which stores dynamic information created by the +user (for instance, the addresses or the todo information), or a resource +database, which tend to be static (for instance the applications). +</para> + +<para> +The Generic DB Viewer is a tool to view and analyze databases stored on +your handheld, especially record databases. It helps a lot creating new conduits +and to debug existing ones. + +<warning><para> +While it is possible use the database viewer to edit, add and delete records, you +should really know what you are doing, otherwise you may damage your data. Use +the viewer applications or conduits to edit your &handheld; data instead, in a +normal usage scenario. +</para></warning> + +</para> + + + +<screenshot> +<screeninfo>The Generic DB Viewer</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="db-app.png" format="PNG"/></imageobject> +<textobject><phrase>The Generic DB Viewer</phrase></textobject> +<caption><para>The Generic DB Viewer</para></caption> +</mediaobject> +</screenshot> + +</sect2> + + +<sect2 id="installer-app"> +<title>The File Installer</title> +<para> +Just hit the +<guibutton>Add File...</guibutton> button to add a file to the +<guilabel>Files to Install:</guilabel> list. These files will +be installed on your &PalmPilot; during the next &HotSync; if +<guilabel>Sync Files</guilabel> +is checked in the conduits section of the +<link linkend="configure">configuration dialog</link>. +If you choose not to +install these files on the &PalmPilot;, just hit +<guibutton>Clear List</guibutton> +to remove any pending files. +</para> + +<para> +If you are using the &HotSync; Daemon you may drag and +drop files or &URL;s +onto the docked icon on the toolbar. The file installer application also +supports dragging and dropping into the <guilabel>Files to Install:</guilabel>area. +Provided <guilabel>Sync Files</guilabel> is checked in the +<link linkend="page-general">settings dialog</link> they +will be installed the next time you HotSync. +</para> + +<tip> +<para>An internal copy of the +file is kept, so you can even drag and drop &URL;s from +&konqueror;! +</para> +</tip> + +<screenshot> +<screeninfo>The File Installer</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="file-app.png" format="PNG"/></imageobject> +<textobject><phrase>The File Installer</phrase></textobject> +<caption><para>The File Installer</para></caption> +</mediaobject> +</screenshot> + +</sect2> +</sect1> + +</chapter> + diff --git a/doc/kpilot/wizard-conduits.png b/doc/kpilot/wizard-conduits.png Binary files differnew file mode 100644 index 000000000..c0e248b07 --- /dev/null +++ b/doc/kpilot/wizard-conduits.png diff --git a/doc/kpilot/wizard-connection.png b/doc/kpilot/wizard-connection.png Binary files differnew file mode 100644 index 000000000..a72a6b5a5 --- /dev/null +++ b/doc/kpilot/wizard-connection.png diff --git a/doc/kpilot/wizard-general.png b/doc/kpilot/wizard-general.png Binary files differnew file mode 100644 index 000000000..2a2d3d9d6 --- /dev/null +++ b/doc/kpilot/wizard-general.png diff --git a/doc/ktnef/Makefile.am b/doc/ktnef/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/ktnef/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/ktnef/index.docbook b/doc/ktnef/index.docbook new file mode 100644 index 000000000..8e6e33943 --- /dev/null +++ b/doc/ktnef/index.docbook @@ -0,0 +1,75 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&ktnef;"> + <!ENTITY package "kdepim"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The TNEF File Viewer Handbook</title> + +<authorgroup> +<author> +<firstname>Michael</firstname> +<surname>Goffioul</surname> +<affiliation> +<address><email>kde-print@kde.org</email></address> +</affiliation> +</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>2000</year> +<holder>Michael Goffioul</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2004-03-04</date> +<releaseinfo>1.0</releaseinfo> + +<abstract><para>The TNEF File Viewer is an application for TNEF mail attachments.</para></abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>TNEF</keyword> + +</keywordset> + +</bookinfo> + +<chapter id="introduction"> + <title>Introduction</title> + + <para>The TNEF File Viewer allows to handle easily mail attachments using the TNEF format. Those attachements + are usually found in mails coming from <trademark class="registered">Microsoft</trademark> + mail servers and embed the mail properties as well as the actual attachments.</para> + + <para>This utility program allows to perform various operations on those attachements:</para> + <itemizedlist> + <listitem><para>Extract actual attachments</para></listitem> + <listitem><para>View message properties (TNEF/MAPI)</para></listitem> + <listitem><para>View/extract message formatted text (in RTF format)</para></listitem> + </itemizedlist> + +</chapter> + +<chapter id="credits"> + <title>Credits and License</title> + + <para>TNEF File Viewer (KTnef)</para> + + <para>Program copyright 2000 Michael Goffioul <email>kde-print@kde.org</email>.</para> + + &underFDL; + &underGPL; + +</chapter> + +</book> diff --git a/doc/kwatchgnupg/Makefile.am b/doc/kwatchgnupg/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/kwatchgnupg/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kwatchgnupg/index.docbook b/doc/kwatchgnupg/index.docbook new file mode 100644 index 000000000..21b614b19 --- /dev/null +++ b/doc/kwatchgnupg/index.docbook @@ -0,0 +1,282 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY gnupg "<acronym>GnuPG</acronym>"> + <!ENTITY gpgconf "<application>GPGConf</application>"> + <!ENTITY watchgnupg "<application>WatchGnuPG</application>"> + <!ENTITY kwatchgnupg "<application>KWatchGnuPG</application>"> + <!ENTITY kappname "&kwatchgnupg;"> + <!ENTITY package "kdepim"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kwatchgnupg; Handbook</title> + +<authorgroup> +<author> +<firstname>Marc</firstname> +<othername></othername> +<surname>Mutz</surname> +<affiliation> +<address><email>mutz@kde.org</email></address> +</affiliation> +</author> + +<othercredit role="developer"> +<firstname>Steffen</firstname> +<surname>Hansen</surname> +<contrib>Developer</contrib> +<affiliation> +<address><email>steffen@klaralvdalens-datakonsult.se</email></address> +</affiliation> +</othercredit> + +<othercredit role="developer"> +<firstname>David</firstname> +<surname>Faure</surname> +<affiliation> +<address><email>faure@kde.org</email></address> +</affiliation> +<contrib>Developer</contrib> +</othercredit> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<legalnotice>&GPLNotice;</legalnotice> + +<date>2004-05-09</date> +<releaseinfo>1.0</releaseinfo> + +<abstract> +<para> +&kwatchgnupg; is a simple &gnupg; log viewer. +</para> +</abstract> + + +<keywordset> +<keyword>KDE</keyword> +<keyword>Kapp</keyword> +<keyword>gpg</keyword> +<keyword>gpgsm</keyword> +<keyword>GnuPG</keyword> +<keyword>Log viewer</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> <title>Introduction</title> + +<para>&kwatchgnupg; is simple &gnupg; log viewer for the upcoming +&gnupg; versions 1.4 and 2.0. It works as a <acronym>GUI</acronym> +wrapper around the command line tool &watchgnupg;, which listens on a +socket for log lines from the &gnupg; backend applications. See +<userinput>info watchgnupg</userinput> for more information about +&watchgnupg;.</para> + +<para>&kwatchgnupg; can be started from the +<menuchoice><guimenu>Tools</guimenu></menuchoice> menu of both +<application>Kleopatra</application> and +<application>KMail</application>, as well as from the command +line. The &kwatchgnupg; executable is named +<userinput>kwatchgnupg</userinput>. +</para> + +</chapter> + +<chapter id="mainfunc"><title>Main Functions</title> + +<sect1 id="mainfunc.viewing"><title>Viewing the Log</title> + +<para> +&kwatchgnupg;'s main function is of course to present the &gnupg; +debugging and logging information to the user. The main window is +divided into a large text viewing area, where &gnupg; messages will +appear as they are generated, a toolbar giving quick access to the most +often needed functions, as well as the obligatory menu bar. +</para> + +<para> +Each line in the text view is normally prefixed with a +<acronym>FD</acronym> identifier and a time stamp in ISO format. The +<acronym>FD</acronym> identifier can be used to distinguish between +output from different &gnupg; instances running in parallel. Following +the timestamp is the name of the component that is the source of the +log line, together with some internal information in sqare brackets, +followed by the original debugging or log output as printed by the +component. +</para> + +<para> +By default, the number of log lines that are kept in the history is +limited to 1000 lines. You can configure the history size in the +configuration dialog. +</para> + +</sect1> + +<sect1 id="mainfunc.saving"> +<title>Saving the Contents of the Log Window to a File</title> + +<para> +Sometimes it might be convenient to save the current log window +contents to a file, e.g. to mail it to the developers as part of a bug +report. There are two ways to achieve this in &kwatchgnupg;: +</para> + +<para> +First, you can choose +<menuchoice><guilabel>File</guilabel><guimenuitem>Save +As...</guimenuitem></menuchoice> (or the corresponding toolbar icon) +to save the complete log window contents to a file. You will be +prompted to specify a save file location. +</para> + +<para> +Second, you can select the interesting lines with normal left-mouse +selection and paste them into a word processor or mail user agent, +just like any other text. You should make sure, though, that lines are +not broken, since this reduces the readability of the log. +</para> + +</sect1> + +<sect1 id="mainfunc.clear"><title>Clearing the Log Window</title> + +<para> +For convenience, you can instruct &kwatchgnupg; to clear the log +window using <menuchoice><guimenu>File</guimenu><guimenuitem>Clear +History</guimenuitem></menuchoice> (or the corresponding toolbar +icon). +</para> + +<para> +Use this prior to starting the crypto operation that you want to +monitor to get only the output from that operation. You can then save +the log using <menuchoice><guimenu>File</guimenu><guimenuitem>Save +As...</guimenuitem></menuchoice> as described above. +</para> + +<para> +Clearing the log discards any previous log window contents. If you are +unsure about whether you'll need the current contents afterwards, you +should save them to a file (see above) before clearing. +</para> + +</sect1> + +</chapter> + +<chapter id="configure"><title>Configuring &kwatchgnupg;</title> + +<para> +To configure &kwatchgnupg;, select +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +&kwatchgnupg;</guimenuitem></menuchoice>, or the corresponding toolbar +icon. &kwatchgnupg;'s configure dialog is divided into two parts, each +of which will be described below. +</para> + +<sect1 id="configure.watchgnupg"><title>&watchgnupg; Settings</title> + +<para> +&watchgnupg; is the process that actually monitors the logging socket +for activity and formats the lines as seen in the &kwatchgnupg; text +view. Settings in this group are passed down to the backend using +the &gpgconf; mechanism. +</para> + +<para> +<guilabel>Executable</guilabel> contains the path to the &watchgnupg; +application. If &watchgnupg; is in your <varname>$PATH</varname>, you +can keep the default <userinput>watchgnupg</userinput>. If +&watchgnupg; is not in your <varname>$PATH</varname>, or if you have +more than one version installed, enter the absolute filename of the +watchgnupg executable here. +</para> + +<para> +<guilabel>Socket</guilabel> contains the socket that &watchgnupg; +should listen on. A change here is distributed to all &gnupg; backend +modules using &gpgconf;, so you don't need to change this setting if +your &gnupg; config files have another <varname>log-file</varname> +set. +</para> + +<para> +<guilabel>Default log level</guilabel> determines the amount of +logging information returned by the backend modules. See the +&watchgnupg; documentation for what level includes which +information. A change here is distributed to all &gnupg; backend +modules using &gpgconf;, so you don't need to change this setting if +your &gnupg; config files have another <varname>log-level</varname> +set. +</para> + +</sect1> + +<sect1 id="configure.logwindow"><title>Log Window Settings</title> + +<para> +Here, you can configure the size of the history buffer, &ie; the +number of log lines that is kept. If more lines have been emitted by +the &gnupg; backend since the last clearance of the history, then the +oldest lines are discarded until there is enough room for the new +lines again. +</para> + +<para> +You can disable the history size limit by clicking <guibutton>Set +Unlimited</guibutton>. Note, however, that &kwatchgnupg;'s memory +consumption will grow with the number of lines it currently +displays. If you use an unlimited history size, then make sure to run +&kwatchgnupg; only for short operations, or regularly clear the +history manually. +</para> + +</sect1> + +</chapter> + +<chapter id="credits-and-license"> +<title>Credits and License</title> + +<para>&kwatchgnupg; copyright 2004 Klarälvdalens Datakonsult AB</para> + +<para>Documentation copyright 2004 Klarälvdalens Datakonsult AB</para> + +<itemizedlist> +<title>Contributors</title> +<listitem> +<para>Steffen Hansen <email>hansen@kde.org</email></para> +</listitem> +<listitem> +<para>Marc Mutz <email>mutz@kde.org</email></para> +</listitem> +<listitem> +<para>David Faure <email>faure@kde.org</email></para> +</listitem> +</itemizedlist> + +&underGPL; +&underFDL; +</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 +--> |
