tdepim/doc/kpilot/configuration.docbook

<chapter id="configure">
<title>Configuring &kpilot;</title>

<para>
Once &kpilot; is installed it needs to be
configured
to match your hardware.
The <link linkend="config-conduits">conduits</link>
need to be configured as well.
After that you can use &kpilot;
to synchronize your &PalmPilot; with
your &kde; desktop or view
data from your &PalmPilot; with the
<link linkend="builtin">built-in viewers</link>.
</para>

<para>
When you run &kpilot; from either
the panel menu or from the command prompt for the first time
it will prompt you with
a dialog box to configure it.
This configuration dialog can be requested later
from the main application
<menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure &kpilot;</guimenuitem>
</menuchoice>
menu, from the &kpilot; daemon popup menu
<menuchoice>
<guimenuitem>Configure KPilot...</guimenuitem>
</menuchoice>
menu item or by starting &kpilot;
from the shell
as follows:
<screen width="40"><prompt>$ </prompt> <userinput><command>kpilot</command><option>--setup</option></userinput>
</screen>
In addition, if you upgrade &kpilot; and some new configuration
options require your attention, this setup dialog will reappear.
</para>

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


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

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

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

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

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


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

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


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

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

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


</sect1>


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

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

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


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

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

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


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

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

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


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

</listitem>
</varlistentry>

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

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

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

</variablelist>

</sect2>

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

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

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

<screenshot>
<screeninfo>The &HotSync; setup page</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="setup-hotsync.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>The &HotSync; Page</phrase>
</textobject>
<caption>
<para>The &HotSync; setup page</para></caption>
</mediaobject>
</screenshot>


<variablelist>
<varlistentry>

<term><guilabel>Default Sync</guilabel></term>

<listitem>
<para>
Select the type of synchronization that will be performed by default.
</para>

<itemizedlist>

<listitem>
<para>
<guilabel>HotSync</guilabel>: run all selected conduits, sync the databases
with a modified flag set, updating the modified records only. Performs a fast
backup, backing up only the databases that were modified. This option offers
a nice balance between speed and data safety.
</para>
</listitem>

<listitem>
<para>
<guilabel>FastSync</guilabel>: Only synchronize those
databases that have conduits, and perform no backup of the data
on the &PalmPilot;, reducing greatly the time required for the sync
operation. This also means that if something goes wrong with your &PalmPilot;,
you may not be able to recover the databases. This is a classic
trade-off between speed and safety.
</para>
</listitem>

<listitem>
<para>
<guilabel>FullSync</guilabel>: run all selected conduits, and sync all
databases, reading all records, and performing a full backup. It is the safest
option, but takes the longest time to complete, as it will merge all the records
from the &handheld; and your desktop. It is the &kpilot; equivalent of the Palm
SlowSync.
</para>
</listitem>

<listitem>
<para>
<guilabel>Copy PC to handheld</guilabel>: run all conduits and sync all
databases, but instead of merging the information from both sources, copy the PC
data to the handheld. <emphasis>Use with care, as this option erases the changes
you made in your handheld since the last sync</emphasis>.
</para>
</listitem>

<listitem>
<para>
<guilabel>Copy handheld to PC</guilabel>: run all conduits and sync all
databases, but instead of merging the information from both sources, copy the
handheld data to the PC. <emphasis>Use with care, as this option erases the
changes you made in your PC since the last sync</emphasis>.
</para>
<warning>
<para>
Remember, when &kpilot; does a &HotSync; and runs the conduits,
the databases in the internal viewers are <emphasis>not</emphasis>
updated. To update the internal viewers, use the FullSync or backup actions.
</para>
</warning>

</listitem>

</itemizedlist>

</listitem>
</varlistentry>


<varlistentry>
<term><guilabel>Do full backup when changing PCs</guilabel></term>
<listitem>
<para>
If you &HotSync; your &handheld; with multiple <acronym>PC</acronym>s, the flag
on the &handheld; that stores which
records have changed since the last &HotSync; may be inaccurate. It is
recommended to do a full sync when changing <acronym>PC</acronym>s. You can
disable the full sync by unchecking this box.
</para>
</listitem>
</varlistentry>
<!--
<varlistentry>
<term><guilabel>Do not sync when screen saver is active</guilabel></term>
<listitem>
<para>
This is a security feature that prevents the &handheld; from synchronization
while the PC screen saver is active. This prevents other people from
stealing your data through the &handheld; cradle while your PC is
unattended. The feature only works with the &kde; screen savers, though,
and you will need to disable it to use &kpilot; in non-&kde; environments.
</para>
</listitem>
</varlistentry>
-->
<varlistentry>
<term><guilabel>Conflict Resolution</guilabel></term>
<listitem>
<para>
Data records can be changed both on the &handheld; and
on the <acronym>PC</acronym>. If one record has incompatible changes
in both the &handheld; and the <acronym>PC</acronym>, (such as
changing a phone number in different ways on both sides),
the conflicting change needs to be resolved so
that the &handheld; and the <acronym>PC</acronym> data are consistent again.
Choices for conflict resolution are:
</para>
<itemizedlist>
<listitem><para><guilabel>Ask User</guilabel>:
pop up a dialog for the user to
choose how the conflict is to be resolved for
every conflict.
</para></listitem>
<listitem><para><guilabel>Do Nothing</guilabel>:
 leave the entries in an inconsistent state.
Future syncs may not notice the discrepancy.
</para></listitem>
<listitem><para><guilabel>Handheld Overrides</guilabel>:
copy the values from the &handheld; to the <acronym>PC</acronym>,
discarding the changes on the <acronym>PC</acronym>.
</para></listitem>
<listitem><para><guilabel>PC Overrides</guilabel>:
copy the values from the <acronym>PC</acronym> to the &handheld;,
discarding changes on the &handheld;.
</para></listitem>
<listitem><para><guilabel>Values From Last Sync (if possible)</guilabel>:
&kpilot; stores a backup copy of the information on your &handheld; depending on
the synchronization method you selected. If this information is available, use
neither
the values from the &handheld; nor the PC, but the values from
the last sync.
</para></listitem>
<listitem><para><guilabel>Use Both Entries</guilabel>:
Create duplicate entries of the conflicting records on both the
<acronym>PC</acronym> and
&handheld;, one with the value from the <acronym>PC</acronym>, the other with
the value
from the &handheld;.
</para></listitem>
</itemizedlist>
</listitem>
</varlistentry>

</variablelist>

</sect2>


<sect2 id="page-backup">
<title>Backup Setup</title>

<para>
This page contains settings specific to the backup operation, which saves
a copy of the the &handheld; databases, allowing the user to
restore this information later.
</para>

<para>In short, databases are all files stored in your &handheld;. A database
can be either a record database, which stores dynamic information created by the
user (for instance, the addresses or the todo information), or a resource
database, which tend to be static (for instance the applications).</para>

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

<variablelist>
<varlistentry>
<term><guilabel>Databases</guilabel></term>
<listitem>
<para>
List databases that should not be synced or backed up.
</para>

<para>
The values can be either database creator values, which are 4-letter strings
surrounded by square brackets (so for Handbase databases you fill in
<userinput>&#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 address book or the calender. Check this box to perform both operations
on
every backup.
</para>
</listitem>
</varlistentry>


</variablelist>

</sect2>


<sect2 id="page-viewers">
<title>Internal Viewers Setup</title>
<para>
&kpilot; contains <quote>viewers</quote> for
presenting information from the &PalmPilot;.
These viewers present the databases available on
the &PalmPilot; in much the same way that the device
itself does. Not all databases have an application-specific
viewer, though you can use the generic database viewer for those.
The viewers page contains settings for the internal viewers in
&kpilot;.
These settings change the way in which the data is shown.
</para>

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

<variablelist>
<varlistentry>
<term><guilabel>Make internal viewers editable</guilabel></term>
<listitem><para>
The internal viewers can be read only or editable. The editable mode allows you
to add new records, delete or edit the existing records and sync your
modifications back to the &handheld;. Check
this box to set the internal viewers to editable mode, uncheck to set them to
read
only mode.</para>
<warning><para>
On some &kpilot; versions, it is not possible check this box, and therefore to
use the internal viewers as editors.
</para></warning>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Show private records</guilabel></term>
<listitem><para>
In your &PalmPilot; you can mark some records as <quote>private</quote>. By
default, &kpilot; does not display these records on the screen. Check this box
if you want to see them.
</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Address Viewer</guilabel></term>
<listitem><para>
Set there the options for the address internal viewer.

<itemizedlist>
<listitem><para>
<guilabel>Show as "Last, first"</guilabel> or
<guilabel>Show as "Company, last"</guilabel>: the order and display of the
address records in the address internal viewer can be set to match the
&handheld;. Select the option that suits better your personal preferences.
</para></listitem>

<listitem><para>
<guilabel>Use key field</guilabel> Check this box to combine entries with the
same last name.
</para></listitem>

</itemizedlist>

</para></listitem>
</varlistentry>


</variablelist>

</sect2>



<sect2 id="page-startup-exit">
<title>Startup and Exit Behavior Setup</title>

<para>
This pages present options related to the startup and exit of &kpilot; and
&kpilot; daemon.
</para>

<para>
While &kpilot; is the front-end for the internal viewers, configuration options
and logs, the sync operation is handled by the &kpilot; daemon. Even if &kpilot;
is not running you can &HotSync; if the daemon is. Therefore, if you want to
be able to sync your &handheld; at anytime, it is important to start the daemon
at login, or the opposite, if you want to be able to sync only when &kpilot; is
running, you have to stop the daemon on exit. The last option is especially
usefull if you have other applications that use the same port as &kpilot;.
</para>


<screenshot>
<screeninfo>Startup and Exit Page</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="setup-startup-exit.png"
format="PNG"/></imageobject>
<textobject><phrase>The Startup and Exit Page</phrase></textobject>
<caption><para>The Startup and Exit Page</para></caption>
</mediaobject>
</screenshot>


<variablelist>

<varlistentry>
<term><guilabel>Startup Options</guilabel></term>

<listitem>
<para>

<itemizedlist>
<listitem>
<para>
<guilabel>Start daemon at login</guilabel>:
By checking this, a link to
the daemon is placed in your autostart folder
and will be started automatically.  Note that this is not normally
needed if the daemon is docked in the panel.
<!-- TODO: broken functionality -->
</para>
</listitem>

<listitem>
<para>
<guilabel>Show daemon in panel</guilabel>:
Check this box to instruct the daemon to place a &kpilot; icon
<guiicon>
<inlinemediaobject>
<imageobject><imagedata fileref="kpilot.png" format="PNG"/>
</imageobject>
</inlinemediaobject>
</guiicon>
in the system tray. This icon has a menu that can be brought up with
the right mouse button. Without this option, the daemon is not visible to the
user at all.
</para>
</listitem>
</itemizedlist>

</para>
</listitem>

</varlistentry>

<varlistentry>

<term>
<guilabel>Exit Options</guilabel>
</term>

<listitem>
<para>

<itemizedlist>
<listitem>
<para>
<guilabel>Quit after HotSync</guilabel>: When this option is enabled, both
&kpilot; and the &kpilot; daemon will exit after the &HotSync; operation has
completed, leaving the device port free for other tools. This may be needed on
systems where the &USB; daemon starts &kpilot; automatically.
</para>
</listitem>

<listitem>
<para>
<anchor id="stopdaemononexit"/>
<guilabel>Stop daemon on exit</guilabel>: Setting this option will cause the
daemon to exit when you quit &kpilot;, leaving the device port free for other
&PalmPilot;-synchronization tools such as <application>malsync</application>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</varlistentry>

</variablelist>

</sect2>
</sect1>

<sect1 id="config-conduits">
<title>Conduits Setup</title>

<para>
Conduits are programs that interface your &handheld; data with
<acronym>PC</acronym> applications or sync your &handheld; data with files
that can be used by <acronym>PC</acronym> applications. They can be
written by third parties, to interface your &PalmPilot; to any application
imaginable.
</para>

<para>
&kpilot;'s configuration dialog allows you to select which conduits
to run during a &HotSync; and to configure those conduits.
A window similar to the following will be displayed:
</para>
<screenshot>
<screeninfo>The Conduit Setup Dialog</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="setup-conduit.png" format="PNG"/></imageobject>
<textobject>
<phrase>The Conduit Setup Dialog</phrase>
</textobject>
<caption>
<para>The Conduit Setup Dialog</para>
</caption>
</mediaobject>
</screenshot>
<para>
Check the box to the left of the conduit name to make it active, uncheck to make
it inactive or click on the conduit name to configure it.
</para>

<variablelist>

<varlistentry>
<term><guilabel>KNotes / Memos</guilabel></term>
<listitem>
<para>
Synchronizes the Memo Pad application with &knotes;.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Notepad</guilabel></term>
<listitem>
<para>
Exports the free hand notes  of the &handheld;'s Notepad application as pictures
to the PC.
</para>
</listitem>
</varlistentry>


<varlistentry>
<term><guilabel>Time Synchronization</guilabel></term>
<listitem>
<para>
Sets the &handheld;'s time to that of the desktop machine.
Useful for keeping the clock of the &handheld; accurate.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Calendar (KOrganizer)</guilabel></term>
<listitem>
<para>
Synchronizes the Datebook application with &korganizer; or with an
iCalendar file of
your choice.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Palm DOC</guilabel></term>
<listitem>
<para>
Automatically converts and installs text files in the &PalmPilot;
DOC format, so you can read the text files with most DOC-capable
applications on the &handheld;.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Addressbook</guilabel></term>
<listitem>
<para>
Synchronizes the Address application with &kaddressbook; or with a vCard file of
your choice.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>System Information</guilabel></term>
<listitem>
<para>
Writes information about your &handheld;, (such as OS version,
RAM available, and the list of databases) to a file. Useful mostly for
debugging purposes.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>ToDo's (KOrganizer)</guilabel></term>
<listitem>
<para>
Synchronizes the Todo list application with &korganizer; or with a iCalendar
file of
your choice.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>MAL (AvantGo) Conduit</guilabel></term>
<listitem>
<para>
Synchronizes your &handheld; with the &AvantGo; server. The &AvantGo; server
offers general content (news, guides, stock quotes, &etc;) in a format that is
suitable for reading in a &handheld;. To use this conduit, you need to register,
subscribe
the channels you select and install the &AvantGo; software on your &handheld;.
</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Mail</guilabel></term>
<listitem>
<para>
Sends mail written on the &handheld; through &kmail;.
There is no provision for receiving mail, however.
</para>
</listitem>
</varlistentry>

</variablelist>


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

<para>
The &knotes; Conduit is a partial replacement for the built-in <link
linkend="builtin">memo application</link>.  It keeps the notes you write
with &knotes; synchronized with the memos you write on your &PalmPilot;.
</para>

<para>
Setting up the &knotes; conduit is very simple.
</para>

<screenshot>
<screeninfo>&knotes; Conduit Setup</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="conduit-knotes.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>&knotes; Conduit Setup</phrase>
</textobject>
<caption>
<para>&knotes; Conduit Setup</para>
</caption>
</mediaobject>
</screenshot>

<para>
In the <guilabel>General</guilabel> Tab there are two configuration options:

<variablelist>

<varlistentry>
<term><guilabel>Delete KNote when Pilot memo is deleted</guilabel></term>
<listitem>
<para>
Uncheck this box if you wish to maintain the note on &knotes; even if the
correspondent memo was deleted on the &handheld; memo application.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Suppress delete-confirmation in KNotes</guilabel></term>
<listitem>
<para>
If the <guilabel>Delete KNote when Pilot memo is deleted</guilabel> box is
checked, you may check this box to automatically delete the notes that
correspond to a deleted memo, without confirmation.
</para>
</listitem>
</varlistentry>

</variablelist>

<note>
<para>
By default, the options <quote>delete knote</quote> and <quote>suppress
delete-confirmation</quote> are turned <emphasis>off</emphasis>, so that notes
will accumulate on your PC.
</para>
</note>

</para>
</sect2>

<sect2 id="notepad-cond">
<title>Notepad Conduit Setup</title>

<para>
The Notepad Conduit exports the free hand notes of the &handheld;'s Notepad
application  as pictures to the desktop. To set the folder to which the pictures
should be exported, either enter it in the <guilabel>Output</guilabel> edit
box or select it clicking the file picker button.
</para>

</sect2>

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

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


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

</sect2>

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

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

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

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

<variablelist>

<varlistentry>
<term><guilabel>Calendar Destination</guilabel></term>
<listitem>
<para>
Choose between synchronizing with the <guilabel>Standard Calendar</guilabel>,
or in other words, the &korganizer; standard calendar or with a
<guilabel>Calendar file</guilabel> of your choice, that you must either
write in the <guilabel>Calendar file</guilabel> edit box or select using the
file picker.
</para>

<warning>
<para>
You can use the calendar conduit with any application that accepts a file in
the iCalendar format as a resource. However, some applications, like Evolution,
do not handle the synchronization gracefully while they are open. As a rule of
thumb, quit these applications before synchronizing, otherwise you will lose
data. There is no need to take these precautions when syncing with &korganizer;
or &kontact;.
</para>
</warning>
</listitem>
</varlistentry>

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

</variablelist>

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

</sect2>


<sect2 id="conduit-palmdoc">
<title>Palm DOC Conduit Setup</title>

<para>
The Palm DOC conduit converts text files in your <acronym>PC</acronym> from and
to
databases in Palm DOC format in the &PalmPilot;. You can use any Palm DOC reader
to view these files on your &PalmPilot;.
</para>

<screenshot>
<screeninfo>Palm DOC Conduit Setup</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="conduit-palmdoc.png"
format="PNG"/></imageobject>
<textobject><phrase>Palm DOC Conduit Setup</phrase></textobject>
<caption><para>Palm DOC Conduit Setup</para></caption>
</mediaobject>
</screenshot>

<important><para>
After changing the Palm DOC conduit configuration, you have to restart &kpilot;
to let the changes you made take effect.
</para></important>

<para>
In the <guilabel>General</guilabel> page, you can set the location of the text
documents in your computer and the direction of the synchronization.
</para>

<variablelist>

<varlistentry>
<term><guilabel>Text files:</guilabel></term>
<listitem><para>
Type on the text box or use the file picker to select the location of the folder
that the Palm DOC conduit uses a as the place for the text files it will sync
with the &handheld;. There, you may place the text documents you want install or
synchronize to the <acronym>PDA</acronym>, and find the text documents created
from Palm DOC
databases in your &handheld;.
<important><para>
The file name has to end in <literal role="extension">.txt</literal> for the
conduit to recognize it as text. If the file is not recognized as text, it will
be ignored by the conduit. Also, the text has to be in an encoding that is
compatible with your &handheld; encoding. Therefore, if the text file has
characters that are not being correctly recognized by the Palm DOC reader in
your &handheld;, try opening the file a text editor, like &kwrite;, and saving
it in an compatible text encoding using the <guilabel>Save As..</guilabel>
dialog, or set the encoding in the <guilabel>PC -> Handheld</guilabel> tab.
</para></important>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Local copy:</guilabel></term>
<listitem><para>
If you want to save a copy of the Palm DOC databases from your &handheld; in
your computer, check the <guilabel>Local copy:</guilabel> box and
type on the text box or use the file picker to select the location of the folder
where these databases will be saved.
</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Synchronization Mode</guilabel></term>
<listitem><para>
The Palm DOC conduit has the ability to sync from and to the &handheld;,
automatically converting the text files to Palm DOC databases and vice versa.
The <guilabel>Sync only PC to PDA</guilabel> option will convert all text files
located in the folder you selected above to Palm DOC databases and install them
in your &handheld;.
The <guilabel>Sync only PDA to PC</guilabel> option will convert all Palm DOC
databases from your &handheld; to files and install them in the
folder you selected above. Finally, The <guilabel>Sync all</guilabel> option
allows the synchronization to work in both directions.

<note><para>
When both the text file and the Palm DOC database are modified, you cannot merge
the modifications, you have to choose one of the versions, losing the changes
in one of them.
</para></note>
</para></listitem>
</varlistentry>

</variablelist>

<para>
In the <guilabel>PC -> Handheld</guilabel> page, you can configure the Palm DOC
compression and bookmarks settings to use when converting from text files to
Palm DOC databases.
</para>

<variablelist>

<varlistentry>
<term><guilabel>Compress</guilabel></term>
<listitem><para>
Palm DOC documents can be compressed, saving considerable amounts
of available memory in your &handheld;. Most Palm DOC readers support
compressed documents, but if you use a reader or editor that is not compatible
with compression (for instance, the Sied editor), you will not be able to read
or edit the compressed Palm DOC documents created by this conduit.
Therefore, check this box to save &handheld; memory, but uncheck it if you have
compatibility problems with compressed Palm DOC in your favorite editor or
reader.
</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Convert bookmarks</guilabel></term>
<listitem><para>
The Palm DOC format has a provision for bookmark records. Bookmarks allow you to
easily jump to selected parts of the document, making browsing long documents
easier. Check this box to allow the Palm DOC conduit to create bookmark records.
To create them, the conduit has to know the location in the text and the name of
the bookmark. There are three supported ways to let the conduit know the
location and name of the bookmark: from inline tags in the text, from tags at
the end of the text and from a <literal role="extension">.bmk</literal> bookmark
file. To make the creation of bookmarks effective, you have to check at least
one of these boxes below.
</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Inline tags in text</guilabel></term>
<listitem><para>
Convert tags in the format &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 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 &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 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>