summaryrefslogtreecommitdiffstats
path: root/doc/kpilot/sync.docbook
blob: 4df681ab33cbc30940ad9ab135dcb20c0d23eeae (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
<chapter id="synchronization">
<title>Syncing your &handheld; with a PC</title>

<para>
This chapter describes the synchronization process
that &kpilot; uses, focusing on the &kpilot; daemon functionality.
You may sync your &handheld; using the <link linkend="builtin">internal
viewers</link> and / or <link linkend="conduits">conduits</link>, depending
on your personal preferences. Conduits allow external applications to interface
with the data on your &handheld;.
</para>

<para>
It is a good idea to make a <link linkend="backup">backup</link>
of your &handheld; regularly. Other than making backups, it should rarely be
necessary to do anything other than drop your &handheld; on the cradle and press
the &HotSync; button. The &kpilot; daemon icon in the system tray will flash
indicating that a sync is under way.
</para>


<screenshot>
<screeninfo>&kpilot; Daemon Pop-Up Menu</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="daemon-menu.png" format="PNG"/></imageobject>
<textobject><phrase>&kpilot; daemon popup menu</phrase></textobject>
<caption><para>&kpilot; daemon popup menu</para></caption>
</mediaobject>
</screenshot>


<para>
To which type of sync &kpilot; will perform next, you can use the main
application
<link linkend="menu-file">
<menuchoice>
<guimenu>File</guimenu>
</menuchoice>
menu</link>,
or right click the &kpilot; daemon icon located in the system tray,
and select one of the menu items under the
<menuchoice>
<guisubmenu>Next Sync</guisubmenu>
</menuchoice>
sub menu.
<tip><para>
If you hover over the &kpilot; daemon icon, a tooltip will appear showing you
what the type of sync &kpilot; will perform next.
</para></tip>

</para>



<para>
In short, the sync types are:
</para>

<itemizedlist>

<listitem><para>
<guilabel>HotSync (once)</guilabel>: this option offers
a nice balance between speed and data safety.
</para></listitem>

<listitem><para>
<guilabel>FastSync (once)</guilabel>: only sync those
databases that have conduits.
</para></listitem>

<listitem><para>
<guilabel>FullSync (once)</guilabel>: the safest option, but
takes the longest time to complete.
</para></listitem>

<listitem><para>
<guilabel>Backup (once)</guilabel>: copy all the data from the &handheld; to the
<acronym>PC</acronym>.
</para></listitem>

<listitem><para>
<guilabel>Restore from Backup (once)</guilabel>: copy the data from a previous backup from the PC to the
&handheld;, erasing the data previously held there.

<warning><para>
Use the restore functionality with care, as you can lose all the new
data entered on the &handheld; since the last backup.
</para></warning>
</para>
</listitem>

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

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

</itemizedlist>


<para>
Alternatively, you can change the default syncing behavior of &kpilot; by
choosing the most suitable option in the <link linkend="page-hotsync">&HotSync;
configure dialog</link>.

<note><para>
To configure the conduits or the sync process, you do not need to open the main
&kpilot; application, as the
<menuchoice>
<guimenuitem>Configure KPilot...</guimenuitem>
</menuchoice>
menu item is available on the &kpilot; daemon popup menu as well.
</para></note>

</para>

<sect1 id="backup">
<title>Backing up your &handheld; data</title>

<para>
On every backup, &kpilot; stores a copy of all your &handheld; data under the
<filename class="directory">$TDEHOME/share/apps/kpilot/DBBackup/User Name/</filename>
folder, allowing you to restore that copy later, if needed. The
<filename class="directory">$TDEHOME</filename> environment variable
(typically <filename class="directory">/home/Login Name/.trinity/</filename>)
points to the folder that contains your configuration and data for the &kde;
applications.</para>

<para>
It is a good idea to backup your data often. To perform a backup, you can click
the
<menuchoice>
<guisubmenu>Next Sync</guisubmenu>
<guimenuitem>Backup</guimenuitem>
</menuchoice>
on the &kpilot; daemon icon popup menu or the
<menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Backup</guimenuitem>
</menuchoice>
menu item on the main &kpilot; application menu in order
to make the next sync a backup. Then, just press the &HotSync; button.
</para>

</sect1>

<sect1 id="restore">
<title>Restoring Your &handheld; Data</title>

<para>
The restore operation consist of transferring all the data previously saved on
the <acronym>PC</acronym> to the &handheld;, effectively erasing all the new
data held by the device by returning it to a previous state.
<warning><para>
Use the restore functionality with care, as you can lose all the new
data entered on the &handheld; since the last backup.
</para></warning>
</para>

<para>
The data saved on the last backup is located on the <filename class="directory">$TDEHOME/share/apps/kpilot/DBBackup/User Name/</filename>
folder. The <filename class="directory">$TDEHOME</filename> environment variable
(typically <filename class="directory">/home/Login Name/.trinity/</filename>)
points to the folder that contains your configuration and data for the &kde;
applications.</para>

<para>
The most common use for the restore functionality is to recover from a hardware
or software failure on the device.
The restore function can be accessed from the
main &kpilot; application, and from the &kpilot; daemon. be careful, as
restoring the data is not a common operation. In order
to restore the data at the next sync, click the
<menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Restore</guimenuitem>
</menuchoice>
menu item, then press the &HotSync; button.
</para>

</sect1>


<sect1 id="sync-s">
<title>Selecting the Synchronization Type</title>

<para>
There are three ways to sync your &handheld;, <guilabel>HotSync</guilabel>,
<guilabel>FastSync</guilabel> or <guilabel>FullSync</guilabel>.
</para>

<para>
When you press the &HotSync; button on your &handheld;, &kpilot;'s will run the
default sync operation (usually a <guilabel>HotSync</guilabel>). You can select
the default sync operation in the <link linkend="page-hotsync">&HotSync;
configure dialog</link>. Alternatively, you can click one of the sync options on
the main &kpilot; application
<menuchoice>
<guimenu>File</guimenu>
</menuchoice>
menu or on the &kpilot; daemon popup
<menuchoice>
<guisubmenu>Next Sync</guisubmenu>
</menuchoice>
submenu.

<important><para>
Using the <link linkend="page-hotsync">&HotSync; configure dialog</link>
is the only way to change the default sync operation.
The main &kpilot; application
<menuchoice>
<guimenu>File</guimenu>
</menuchoice>
menu items or the &kpilot; daemon popup
<menuchoice>
<guisubmenu>Next Sync</guisubmenu>
</menuchoice>
submenu items change only the type of sync that will be performed <emphasis>next</emphasis>.
</para></important>
</para>

<screenshot>
<screeninfo>&kpilot; Daemon Pop-Up Menu</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="daemon-menu.png" format="PNG"/></imageobject>
<textobject><phrase>&kpilot; daemon popup menu</phrase></textobject>
<caption><para>&kpilot; daemon popup menu</para></caption>
</mediaobject>
</screenshot>


<para>
For more information on the sync types, please refer to the descriptions
available in <xref linkend="page-hotsync" />.
</para>


</sect1>

<sect1 id="conduits">
<title>Syncing your &handheld; Data Using Conduits</title>

<para>
Conduits are programs that interface your &handheld; data with
<acronym>PC</acronym> applications or sync your &handheld; data with files
that can be used by <acronym>PC</acronym> applications.
</para>

<para>
Conduits can be set up by selecting
<menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure KPilot...</guimenuitem>
</menuchoice>, or using the daemon pop up menu and clicking the
<guimenuitem>Configure KPilot...</guimenuitem>
menu item.
</para>

<screenshot>
<screeninfo>&kpilot; Daemon Pop-Up Menu</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="daemon-menu.png" format="PNG"/></imageobject>
<textobject><phrase>&kpilot; daemon popup menu</phrase></textobject>
<caption><para>&kpilot; daemon popup menu</para></caption>
</mediaobject>
</screenshot>

<para>
The <guilabel>Conduits</guilabel> tree in the configuration dialog
collects all the installed conduits available.
The conduits can be enabled and disabled
by clicking on the check box to the left of the conduit's name.
Conduits can have an extensive configuration of
their own, and may be supplied by third parties.
Most of the conduits require some initial configuration, so it is strongly
recommended to check the
<link linkend="config-conduits">section detailing the default conduits
configuration</link> before using them.
</para>


<para>
The default conduits are the following:
</para>


<variablelist>

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

<important><para>
The conduit only synchronizes the Memo Pad data if &knotes; is running. If you
want to enable this functionality, please remember to start &knotes; first, or
check if it is already running (tip: look for the &knotes; icon in the system tray).
</para></important>

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


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


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

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

<varlistentry>
<term><guilabel>Palm DOC</guilabel></term>
<listitem><para>
Automatically converts, installs and sync text files in the &PalmPilot;
DOC format, so you can read the text files with most DOC-capable
applications on the &handheld;. There are many free or open source Palm
DOC readers, and some Palm DOC editors for your handheld.</para>
<para>
Any plain text file can be easily converted. For instance, you can download and
convert the public domain books provided by the <ulink url="http://www.gutenberg.net">
Gutenberg Project</ulink> and read them in your &handheld;.
</para></listitem>
</varlistentry>

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

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

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

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


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

<varlistentry>
<term><guilabel>Perl</guilabel></term>
<term><guilabel>Python</guilabel></term>
<term><guilabel>NULL</guilabel></term>
<listitem><para>
These conduits are intended as a programming demonstration,
and serve no practical purpose during a &HotSync;.
They are not normally listed, but you may see them on some systems.
</para></listitem>
</varlistentry>

</variablelist>

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


</sect1>

<sect1 id="conflicts">
<title>Resolving Conflicts</title>

<para>
Data records can be changed both on the &handheld; and
on the <acronym>PC</acronym>. If one record has incompatible changes
in both the &handheld; and the <acronym>PC</acronym>, (such as
changing a phone number in different ways on both sides),
the conflicting change needs to be resolved so
that both the &handheld; and the <acronym>PC</acronym> are in sync again.
</para>

<para>
A popup dialog may appear, asking you how to resolve the
conflict, or you may have a general rule to automatically handle these
conflicts (depending on your <link linkend="page-hotsync">conflict resolution
choice</link>). Note that you can define different resolution choices
for different conduits in the <link linkend="config-conduits">conduits
configuration dialog</link>.
</para>

</sect1>
</chapter>