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

BUG:215923


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

1 files changed, 450 insertions, 0 deletions

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>