<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 pop-up menu
<menuchoice>
<guimenuitem>Configure KPilot...</guimenuitem>
</menuchoice>
menu item or by starting &kpilot;
from the shell
as follows:
<screen width="40"><prompt>$ </prompt> <userinput><command>kpilot</command> <option>--setup</option></userinput>
</screen>
In addition, if you upgrade &kpilot; and some new configuration
options require your attention, this setup dialog will reappear.
</para>

<screenshot>
<screeninfo>Configuration Dialog</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="setup-tabs.png" format="PNG"/></imageobject>
<textobject><phrase>The configuration dialog</phrase></textobject>
<caption><para>The configuration dialog</para></caption>
</mediaobject>
</screenshot>


<para>
&kpilot;'s configuration dialog is a large one.
This is because it contains not only the configuration of the
device for communicating with the &PalmPilot;, but also
the configuration of all the installed conduits.
Each group of configuration options
(<link linkend="general-setup">general</link>
and <link linkend="config-conduits">conduits</link>)
will be discussed separately.
We will begin, however, by taking a look at the
<link linkend="configwizard">configuration wizard</link>, which should make most of the
general group of configuration options superfluous.
</para>

<sect1 id="configwizard">
<title>Using the Wizard</title>

<para>
The configuration wizard helps you to set up &kpilot; to communicate
with the &PalmPilot; and to configure the conduits as a group. It's a great
start for new users, and you can always fine tune your preferences later.
</para>

<para>
In the <guilabel>Pilot Info</guilabel> dialog, type your <guilabel>User Name</guilabel>. It
should match the one from the &PalmPilot;. Next, type the file name of
the <guilabel>Device</guilabel> you will use to connect the &PalmPilot; (The
connection can be through a serial port, USB port, infrared, Bluetooth, network
or the generic <filename class="devicefile">/dev/pilot</filename> device.)
Alternatively, click the
<guibutton>Automatically detect handheld and user name...</guibutton>
button and press the &HotSync; button on your &handheld;. The Wizard will try
to find the correct <guilabel>Device</guilabel> and
<guilabel>User Name</guilabel>.
</para>

<important><para>
If the
<guilabel>Device</guilabel> does not have the right permissions, the wizard will
not be able to find it. Normal users must be able to read/write the correct
device. To resolve this issue, please refer to <link
linkend="faq-connection"><quote>&kpilot; says <errorname>Can't connect to pilot</errorname></quote>
&FAQ; entry</link>, or contact your system administrator.
</para></important>


<screenshot>
<screeninfo>The First Configuring Wizard Dialog</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="wizard-general.png" format="PNG"/></imageobject>
<textobject><phrase>Configuring Wizard: The Pilot Info Dialog</phrase></textobject>
<caption><para>Configuring Wizard: The Pilot Info Dialog</para></caption>
</mediaobject>
</screenshot>

<para>
Press the &HotSync; button of your &handheld; to probe for the
correct <guilabel>Device</guilabel> and <guilabel>User Name</guilabel>.
</para>


<screenshot>
<screeninfo>The Second Configuring Wizard Dialog</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="wizard-connection.png" format="PNG"/></imageobject>
<textobject><phrase>Configuring Wizard: The Autodetection Dialog</phrase></textobject>
<caption><para>Configuring Wizard: The Autodetection Dialog</para></caption>
</mediaobject>
</screenshot>

<para>
KPilot has the ability to sync the data on your &handheld; with
applications or files on your <acronym>PC</acronym>. The programs that
perform these actions are called conduits. The sync dialog configures
all applicable &kpilot; conduits to sync with widely used
<acronym>PIM</acronym> suites. You can fine tune these settings later, from the
<menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure &kpilot;</guimenuitem>
</menuchoice>
menu. Please check the <link linkend="config-conduits">conduits configuration</link>
section of this document for more information.
</para>

<screenshot>
<screeninfo>The Third Configuring Wizard Dialog</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="wizard-conduits.png" format="PNG"/></imageobject>
<textobject><phrase>Configuring Wizard: The Sync Dialog</phrase></textobject>
<caption><para>Configuring Wizard: The Sync Dialog</para></caption>
</mediaobject>
</screenshot>


</sect1>


<sect1 id="general-setup">
<title>General Setup</title>

<para>
The settings available in the &kpilot; configuration dialog
under the heading <guilabel>General Setup</guilabel>
give you detailed control over the operation of &kpilot;:
you can select a non-standard hardware device,
set special encodings for foreign-language &handheld;s,
and control how &kpilot; displays your data. There
are five items under the <guilabel>General Setup</guilabel>
heading. You may need to expand the <guilabel>General Setup</guilabel>
heading to see them.
</para>

<screenshot>
<screeninfo>Items under General Setup</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="setup-items.png" format="PNG"/></imageobject>
<textobject><phrase>The items under General Setup</phrase></textobject>
<caption><para>The items under General Setup</para></caption>
</mediaobject>
</screenshot>


<sect2 id="page-general">
<title>Device Setup</title>

<para>
This is a setup page that contains options describing
the &PalmPilot; hardware, you, the user
and how you want the various parts of &kpilot;
to be started.
</para>

<screenshot>
<screeninfo>Device Page</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="setup-general.png" format="PNG"/></imageobject>
<textobject><phrase>The Device Page</phrase></textobject>
<caption><para>The Device Page</para></caption>
</mediaobject>
</screenshot>


<variablelist>
<varlistentry>
<term><guilabel>Pilot device</guilabel></term>
<listitem>
<para>
The port that the cradle is connected to.
By default it is
set to <filename class="devicefile">/dev/pilot</filename>
which should be a symbolic link to the real port.
The port might be a serial port, in which case
<filename class="devicefile">/dev/pilot</filename>
should point to
something like
<filename class="devicefile">/dev/cuaa0</filename>
(in &FreeBSD;) or
<filename class="devicefile">/dev/ttyS0</filename>
(in &Linux;).
For &USB; devices, it can be more difficult to
determine where
<filename class="devicefile">/dev/pilot</filename>
should point.
It may be possible to configure your &USB; daemon
to set up the link automatically, so that
<filename class="devicefile">/dev/pilot</filename>
points to the right port no matter where you plug in your &PalmOS; device.
</para>

<para>
<emphasis>Make sure the port has
the correct permissions.</emphasis>
It
must be read/write by all if &kpilot; is intended to be used by a
normal user! &kpilot; will complain if the permissions are wrong, but you
will need to fix the permissions by hand. This could be done by doing a
<userinput><command>chmod</command> <parameter>666</parameter> <replaceable>device</replaceable></userinput>
as root where <replaceable>device</replaceable> is the correct port.

To resolve this issue, please refer to <link
linkend="faq-connection"><quote>&kpilot; says <errorname>Can't connect to pilot
</errorname></quote>
&FAQ; entry</link>, or contact your system administrator.
</para>


<para>
You can also use network sync (with pilot-link 0.11.5 and later)
by entering <userinput>net:any</userinput> as the
device name.
</para>

</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Speed</guilabel></term>
<listitem>
<para>
Indicate the speed of the <emphasis>serial</emphasis>
connection to the &PalmPilot;.
It has no meaning for &USB; devices.
For an older model &PalmPilot;, choose 9600.
Newer models may be able to handle speeds up to
the maximum listed, 115200.
You can experiment with the connection speed: the &PalmPilot;
manual suggests starting at a speed of 19200 and trying faster
speeds to see if they work.
</para>
</listitem>
</varlistentry>

<varlistentry><term><guilabel>Encoding</guilabel></term>
<listitem>
<para>
&PalmOS; devices are available in
many different languages.
If your device uses a different encoding than
ISO-latin1, you will need to select the
correct encoding from the list in order to
display special characters correctly.
If you can enter Russian in your &PalmPilot;,
select CP1251, for instance.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Pilot user</guilabel></term>
<listitem>
<para>
The user name of the &PalmPilot;.  By default this name is the same as
your log on name.  When you sync with the &PalmPilot; &kpilot; will
check to see if this name matches the one on the &PalmPilot;.  If they do
not, you are asked to pick which you will use.  If you pick the local
name, the &PalmPilot; will be changed to match.
The <guilabel>Pilot User</guilabel> entry  is also used to name the folder that
stores the information from the &PalmPilot;. This folder is created in the
<filename class="directory">$KDEHOME/share/apps/kpilot/DBBackup/</filename>
folder, where the <filename class="directory">$KDEHOME</filename> environment variable
(typically <filename class="directory">/home/Login Name/.kde/</filename>)
points to the folder that contains your configuration and data for the &kde;
applications.
</para>
</listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2 id="page-hotsync">
<title>HotSync Setup</title>

<para>
This page contains settings with which you can instruct
&kpilot; to perform special kinds of &HotSync;,
as well as direct how conflicts during a &HotSync; should be resolved.
A conflict happens when both the desktop application and the &handheld; application
change the same data.
</para>

<para>
&kpilot; interfaces with your &handheld; in two ways: using the
the conduits and the internal viewers. Conduits are plug-in programs which extend
the synchronization capabilities of &kpilot;. &kpilot; stores separate copies of the
databases and records for conduits, while the internal viewers and backup
operation share the same copy. This distinction is important to choose your
update method depending on your usage. If you use mainly the conduits to sync
your &handheld; with external programs, you may choose as default synchronization
method any option that runs the conduits. However, if you use mainly the internal
viewers, you need to update copy of the databases as well in order to
view and edit the information from your &handheld;, so running the conduits only
is not sufficient.
</para>

<warning><para>
Remember, when &kpilot; does a &HotSync; and runs the conduits,
the databases in the internal viewers are <emphasis>not</emphasis>
updated. This will be fixed in a future release.</para>
</warning>

<screenshot>
<screeninfo>HotSync Page</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="setup-hotsync.png" format="PNG"/></imageobject>
<textobject><phrase>The HotSync Page</phrase></textobject>
<caption><para>The HotSync 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></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 screensaver is active</guilabel></term>
<listitem>
<para>
This is a security feature that prevents the &handheld; from synchronization
while the PC screensaver 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 screensavers, 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>&#91;PmDB&#93;</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 addressbook 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 &HotSync; icon
<guiicon>HotSync icon
<inlinemediaobject>
<imageobject><imagedata fileref="toolbar_hotsync.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:
<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>
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>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>

<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>


<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.

<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>

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 &quot;delete knote&quot;
and &quot;suppress delete-confirmation&quot; are
turned <emphasis>off</emphasis>, so that notes will
accumulate on your PC.
</para>
</note>

</para>
</sect2>

<sect2 id="time-cond">
<title>Time Synchronization Conduit Setup</title>

<para>
The Time Synchronization Conduit syncs the &handheld;'s time to that of the desktop
machine. It is useful for keeping the clock of the &handheld; accurate. There
are really no configuration options other that enabling and disabling the
conduit, as currently only one direction for the synchronization is enabled,
you can only <guilabel>Set the handheld time from the time on the PC</guilabel>,
and not <guilabel>Set the PC time from the time on the handheld</guilabel>.
</para>


<note><para>
&PalmOS; Version 3.25 and 3.3 do not support setting the &handheld; system time.
For these systems, the conduit will be simply skipped.
</para></note>

</sect2>

<sect2 id="vcal-cond">
<title>Calendar Conduit Setup</title>

<para>
This conduit will synchronize your &PalmPilot; with &korganizer; and Kontact, or to
an iCalendar file of your choice. In the latter case, the conduit will need the filename of the
calendar file (this will usually be a file that ends in <literal
role="extension">.ics</literal>) to sync with, of if it uses the standard
&korganizer; iCalendar file, it will be under the <filename class="directory">$KDEHOME/share/apps/korganizer/</filename>
folder, where the <filename class="directory">$KDEHOME</filename> environment variable
(typically <filename class="directory">/home/Login Name/.kde/</filename>)
points to the folder that contains your configuration and data for the &kde;
applications.
</para>

<screenshot>
<screeninfo>The Calendar Conduit Setup Dialog</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="conduit-vcal.png" format="PNG"/></imageobject>
<textobject><phrase>Calendar Conduit Setup</phrase></textobject>
<caption><para>Calendar Conduit Setup</para></caption>
</mediaobject>
</screenshot>

<para>
In the <guilabel>General</guilabel> page, you can set the calendar options.
</para>

<variablelist>

<varlistentry>
<term><guilabel>Calendar Destination</guilabel></term>
<listitem><para>
Choose between synchronizing with the <guilabel>Standard Calendar</guilabel>,
or in other words, the &korganizer; standard calendar or with a
<guilabel>Calendar file</guilabel> of your choice, that you must either
write in the <guilabel>Calendar file</guilabel> edit box or select using the
file picker.
</para>
<warning><para>
You can use the calendar conduit with any application that accepts a file in
the iCalendar format as a resource. However, some applications, like Evolution,
do not handle the synchronization gracefully while they are open. As a rule of thumb,
quit these applications before synchronizing, otherwise you will lose data.
There is no need to take these precautions when syncing with &korganizer; or Kontact.
</para></warning>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Store archived records in the KDE calendar</guilabel></term>
<listitem><para>
Check this box to save a copy of the archived records from your
&handheld; on the <acronym>PC</acronym>, in order to keep a history of
past appointments in you &kde; desktop as well.
</para></listitem>
</varlistentry>

</variablelist>

<para>
In the <guilabel>Conflicts</guilabel> page, you can set the calendar options,
overriding &kpilot;'s general settings for conflict resolution when you are using
this conduit. For a detailed description of the different conflict resolution possibilities
available, please refer to the <link linkend="page-hotsync">HotSync Setup section</link> of this
handbook.
</para>

<note id="location-sync"><title>Location of appointments</title>
<para>
For syncing the location of appointments there is a special feature built-in,
because some palm devices do not support a specialized location field in their
database. The location will be synced in the first line of
the notes field, e.g. like 
<computeroutput>*big room, street 20*</computeroutput>.
If you like to enter a location in your Palm, make sure to only use the first line without linebreaks and start and close the first line 
with a star (<userinput>*</userinput>).
</para>
</note>

</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.
</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 &lt;* <replaceable>BookmarkName</replaceable> *&gt;
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 &lt;<replaceable>BookmarkName</replaceable>&gt;
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 a in depth description of the format of the bmk file.
</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
&lt;* <replaceable>BookmarkName</replaceable> *&gt; placing each tag in the place
that was previously referenced by the bookmark, and using the bookmark name as
the <replaceable>BookmarkName</replaceable> text inside the tag. Now you You can
edit the bookmark name, move it or delete it and convert back to Palm DOC, as
you wish.
</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Do not convert, if text unchanged (only bookmarks)</guilabel></term>
<listitem><para>
If you check this box, only changes in the text will trigger conversions from
Palm DOC to text files. In other words, changes in the bookmarks only will not
result in updates for the text files in your computer.
</para></listitem>
</varlistentry>

</variablelist>

<para>
In the <guilabel>Conflicts</guilabel> page, you can configure how the conduit
deals with files that changed both in the computer and the &handheld;.
</para>

<variablelist>

<varlistentry>
<term><guilabel>Conflict Resolution</guilabel></term>
<listitem><para>
The Palm DOC conduit does not feature merging the modifications when a text is
changed both in the &handheld; and in the computer. Therefore, the choice is
between working with the files out of sync, or discarding the changes in one of
them. The <guilabel>No resolution</guilabel> option will avoid synchronizing
texts with conflicts, the <guilabel>PDA overrides</guilabel> option will
overwrite the computer text file version in case of conflict,
the <guilabel>PC overrides</guilabel> will do the same, but the other way around,
and the <guilabel>Ask the user</guilabel> option will bring a dialog to let the
user decide on a file by file, case by case basis.
</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Always show resolution dialog, even when there are no conflicts</guilabel></term>
<listitem><para>
This option will always bring the conflict resolution dialog, even if there is no
conflicts to solve. The advantage is that you can keep track of all the files
that are being covered by the conduit.
</para></listitem>
</varlistentry>

</variablelist>


</sect2>


<sect2 id="conduit-kaddressbook">
<title>&kaddressbook; Conduit Setup</title>

<para>
This conduit will synchronize your &PalmPilot; with the &kde; address book or to
a vCard file of your choice. In the latter case, the conduit will need the filename of the
vCard file (this will usually be a file that ends in <literal
role="extension">.vcf</literal>) to sync with, of if it uses the standard
&kde; address book file, it will be under the
<filename class="directory">$KDEHOME/share/apps/kabc/</filename>
folder, where the <filename class="directory">$KDEHOME</filename> environment variable
(typically <filename class="directory">/home/Login Name/.kde/</filename>)
points to the folder that contains your configuration and data for the &kde;
applications.
</para>

<screenshot>
<screeninfo>The KAddressBook Conduit Setup Dialog</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="setup-address.png" format="PNG"/></imageobject>
<textobject><phrase>KAddressBook Conduit Setup</phrase></textobject>
<caption><para>KAddressBook Conduit Setup</para></caption>
</mediaobject>
</screenshot>

<para>
In the <guilabel>General</guilabel> page, you can set the general address sync options.
</para>

<variablelist>

<varlistentry>
<term><guilabel>Sync Destination</guilabel></term>
<listitem><para>
Choose between synchronizing with the <guilabel>Standard addressbook</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 addressbook</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> addressbook. 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 e-mail 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 <acronym>HTML</acronym>, 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
<trademark>Microsoft</trademark> <trademark>Windows</trademark>, 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 instalations, 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 synchronise 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 enebla 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 respecitve 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.
<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>
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>

<sect2 id="conduit-null">
<title>NULL Conduit Setup</title>

<para>
The NULL conduit is included as a programming example and
has no practical function whatsoever.
</para>
</sect2>

</sect1>


</chapter>
