diff options
37 files changed, 3565 insertions, 1 deletions
diff --git a/Makefile.am b/Makefile.am index 03d2b7c..1a92b00 100644 --- a/Makefile.am +++ b/Makefile.am @@ -2,7 +2,7 @@ ## (C) 1997 Stephan Kulow ## Modified by Adriaan de Groot -SUBDIRS = lib kpilot conduits +SUBDIRS = lib kpilot conduits doc messages: $(EXTRACTRC) `find . -name "*.rc" -o -name "*.ui"` > rc.cpp diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..5c0b20e --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = AUTO +SUBDIRS = $(AUTODIRS) diff --git a/doc/kpilot/CMakeLists.txt b/doc/kpilot/CMakeLists.txt new file mode 100644 index 0000000..a177bb4 --- /dev/null +++ b/doc/kpilot/CMakeLists.txt @@ -0,0 +1,12 @@ +################################################# +# +# (C) 2010-2011 Serghei Amelian +# serghei (DOT) amelian (AT) gmail.com +# +# Improvements and feedback are welcome +# +# This file is released under GPL >= 2 +# +################################################# + +tde_create_handbook( DESTINATION kpilot ) diff --git a/doc/kpilot/Makefile.am b/doc/kpilot/Makefile.am new file mode 100644 index 0000000..6792fc5 --- /dev/null +++ b/doc/kpilot/Makefile.am @@ -0,0 +1,2 @@ +KDE_DOCS = kpilot +KDE_LANG = en diff --git a/doc/kpilot/address-app.png b/doc/kpilot/address-app.png Binary files differnew file mode 100644 index 0000000..171b600 --- /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 0000000..723c8a6 --- /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 0000000..e722499 --- /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 0000000..196961b --- /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 0000000..ad63b35 --- /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 0000000..57b4534 --- /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 0000000..13270cd --- /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 0000000..e0b8979 --- /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">$TDEHOME/share/apps/kpilot/DBBackup/</filename> +folder, where the <filename class="directory">$TDEHOME</filename> environment +variable +(typically <filename class="directory">/home/Login Name/.trinity/</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">$TDEHOME/share/apps/korganizer/</filename> folder, where the +<filename class="directory">$TDEHOME</filename> environment variable (typically +<filename class="directory">/home/user/.trinity/</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">$TDEHOME/share/apps/tdeabc/</filename> +folder, where the <filename class="directory">$TDEHOME</filename> environment +variable (typically <filename class="directory">/home/Login Name/.trinity/</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 0000000..4e7018d --- /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 0000000..f55842a --- /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 0000000..cbc9196 --- /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 0000000..16e8d40 --- /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 0000000..e787e5a --- /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 "tdepim"> +<!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>[email protected]</email></address> + </affiliation> +</author> +<author> + <firstname>Adriaan</firstname> + <othername>de</othername> + <surname>Groot</surname> + <affiliation> + <address><email>[email protected]</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>tdepim</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 +tdepim-users mailing list, <email>[email protected]</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>[email protected]</email></para> +</listitem> +<listitem><para>&Preston.Brown; <email>[email protected]</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>[email protected]</email>. +Documentation copyright 2004,2005 Carlos Leonhard Woelz +<email>[email protected]</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 0000000..8eb613b --- /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 0000000..8c0b4a6 --- /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 0000000..958225c --- /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 0000000..3c4fed2 --- /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 0000000..9ea5a6a --- /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 0000000..e79d71e --- /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 0000000..75b5358 --- /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 0000000..f730a9c --- /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 0000000..0d8b8a7 --- /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 0000000..87e6ef2 --- /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 0000000..96bee4a --- /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 0000000..6c178ed --- /dev/null +++ b/doc/kpilot/sidebar.png diff --git a/doc/kpilot/sync.docbook b/doc/kpilot/sync.docbook new file mode 100644 index 0000000..4df681a --- /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">$TDEHOME/share/apps/kpilot/DBBackup/User Name/</filename> +folder, allowing you to restore that copy later, if needed. The +<filename class="directory">$TDEHOME</filename> environment variable +(typically <filename class="directory">/home/Login Name/.trinity/</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">$TDEHOME/share/apps/kpilot/DBBackup/User Name/</filename> +folder. The <filename class="directory">$TDEHOME</filename> environment variable +(typically <filename class="directory">/home/Login Name/.trinity/</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 0000000..7b54185 --- /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 0000000..d1ab921 --- /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 0000000..11eceb4 --- /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 0000000..803da4b --- /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 0000000..c0e248b --- /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 0000000..a72a6b5 --- /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 0000000..2a2d3d9 --- /dev/null +++ b/doc/kpilot/wizard-general.png |
