1 files changed, 100 insertions, 17 deletions

diff --git a/bin/kdepim/SyncHowto.txt b/bin/kdepim/SyncHowto.txt
index 6c1da16..64f6f14 100644
--- a/bin/kdepim/SyncHowto.txt
+++ b/bin/kdepim/SyncHowto.txt
@@ -6,34 +6,35 @@ HAVE TOO MUCH DIFFERENCE.
 
 In other words: Please make sure, that the clocks of the devices 
 you want to sync have only a difference of some seconds!
 
 
 CONTENT:
 
 0) How syncing works
 1) Qick overview of settings
 2) Sync settings in sync dialog
 3) Syncing background
 4) Sync preferences
-5) Details about sync profile kinds
+5) How a filter works
+6) Details about sync profile kinds
 
 *************************************************************************
 0) How syncing works
 *************************************************************************
 
 Note:
 The recommended and easiest way to syncronize two devices where 
 KO/Pi, KA/Pi or PWM/Pi is installed, is the profile kind "Pi-Sync".
-Details about that in 5) b).
+Details about that in 6) b).
 
 In KDE-Pim/Pi you can synchronize ( sync ) your calendar/addressbook/ 
 passwordfile with another calendar/addressbook/passwordfile,
 by syncing  your (local) calendar/addressbook/passwordfile 
 with a (remote) file. 
 This remote file may on your local filesystem
 or on another (remote) device.
 
 If you want to sync with another remote device, you have to create
 a sync profile.
 You have two choices for choosing the profil kind:
 I)  You can choose profile kind "Remote file" and specify a 
@@ -81,83 +82,131 @@ b) Give your device a unique name.
    That means: It is unimportant if you sync A->B or B->A,
    the devices A and B will be synced properly. 
 c) Create a new sync profile and give it a unique name.
    (unique in the set of all sync profiles on this device).
    If you want to sync with a device, where KO/Pi is already installed
    and which has a given unique device name, use this device name as
    your profile name ( refer to b) ).
 d) Coose the profile kind of your syncing method:
       (i) Local file or
      (ii) Pi-Sync or
     (iii) Remote file or
    (iiii) Mobile Phone.
-   Detailed explanation in 5) 
+   Detailed explanation in 6) 
 e) Choose the other profile options.
    Detailed explanation in 2) 
 f) Close sync dialog with OK.
 g) Sync.
 
 NOTE:
 AFTER SYNCING THERE ARE "SYNC EVENTS" CREATED 
 (OR UPDATED, IF IT ALREADY EXITS) FOR EACH SYNC PROFILE.
 YOU MAY NOT DELETE OR CHANGE THESE EVENTS. 
 
 *************************************************************************
 2) Sync settings in sync dialog
 *************************************************************************
 
 a) Local device name:
    -> 1) b)
 b) Profile:
    -> 1) c)
-c) Include in multiple sync:
+c) Multiple Sync options: Include in multiple sync:
    In the Synchronize menu, there is a multiple sync menu entry.
    If you choose this menu entry, all user defined profiles with this
    'Include in multiple sync' option enabled will be  synced 
    one after another. And this twice. This will take some time.
    After that sync, on all devices should be the same data.
+
+d)- j) Sync algo options:
+
 d) Ask for preferences before sync:
-   Check this to be asked for sync preferences settings before each sync.
+   Check this to be asked for "Sync preferences" settings before each sync.
    If the profile kind is "Pi-Sync" you will be asked to confirm
    the "Pi-Sync" specific settings (Password,IP address, port number)
    as well. That makes it possible to use that profile for a
    device that is connected via DHCP to the network and gets different
-   IP addresses when connection to the network.
+   IP addresses when connecting to the network.
 e) Sync preferences:
    Choose here your sync preferences.
    Details -> 4)
 f) Show summary after sync:
    Check this to get a small summary dialog after sync 
    about number of added/changed/deleted events on local/remote.
+g) Apply filter when adding data to local:
+   What is a filter? You can read this in -> 5)
+   With this option you can specify a filter for events/contacts, 
+   which should be added to the local database, because they are
+   in the remote database and not in the local database.
+   (Database = calendar file or addressbook file).
+   Note that the filter is NOT applied to the remote
+   database before syncing. It is only applied to a particular
+   item which should be added to the local database.
+   Well, but what is the difference?
+   The differnce is: If the remote database AND the local database contain
+   an already synced item, which does not match the filter, then this item is synced.
+   If the remote database contains an item which does not match the filter
+   and the local database does not contain this item, then this item is not added
+   to the local database, but it is still in the remote database after syncing.
 g) Write back synced data:
    Uncheck this to update the local calendar only.
    I.e. your local calendar is synced with the remote calendar
    but nothing on the remote calendar is changed.
    If you uncheck "Write back synced data", the settings
    under h) and i) are ignored, of course.
-h) --Write back (on remote) existing entries only:
+
+h) - j) Write back options:
+
+h) Write back (on remote) existing entries only:
    Check this to update the remote data only.
    I.e. no data from yor local calendar/addressbook is added to the
    remote device. You may use this option to 
    sync against some kind of "public calendar/addressbook" without 
-   writing back your personal data.
-i) --Write back (calendar) entries in future only:
-   Check this to write back only calendar entries in future.
+   adding anything of your personal data.
+   But in this case, you cannot add an item to the remoet device.
+i) Apply filter when adding data to remote:
+   What is a filter? You can read this in -> 5)
+   With this option you can specify a filter for events/contacts, 
+   which should be added to the remote database, because they are
+   in the local database and not in the remote database.
+   (Database = calendar file or addressbook file).
+   Note that the filter is NOT applied to the local
+   database before syncing. It is only applied to a particular
+   item of the local database which should be added to the remote database.
+   Well, but what is the difference?
+   The differnce is: If the local database AND the remote database contain
+   an already synced item, which does not match the filter, then this item is synced.
+   If the local database contains an item which does not match the filter
+   and the remote database does not contain this item, then this item is not added
+   to the remote database, but it is still in the local database after syncing.
+   Example:
+     You have specified a calendar filter "only public events".
+     You specify this filter as the outgoing filter for syncing.
+     If there is an event in the local database which is not "public", but "private",
+     this event is not added to the remote database.
+     If there is an event in the local database and in the remote database which is
+     "private" (maybe added by someone else) then this event is synced and 
+     it is in the local database and in the remote database after syncing.
+     That means in particular you cannot remove an event from the remote
+     database but setting it to "private". 
+     If you want to remove the event you can clone it, set it to private and delete the
+     original event. Then the original event is deleted in the remote database after sync and
+     the cloned event is not added to the remote database, because it is private.
+j) Write back (calendar) entries for time period only:
+   Check this to write back only calendar entries for a given time period.
    (Useful when syncing with mobile phones.)
-   You can specify the date range in weeks with
-   ---- Max. weeks in future.
-   Note: The date range starts always 7 days before the actual date!
-   I.e. the calendar events of the last week are written back always.
-j) Profile kind:
-   Details -> 5)
+   You can specify the date range in weeks for the weeks in the past to the weeks in the future.
+
+k) Profile kind:
+   Details -> 6)
 
 *************************************************************************
 3) Syncing background
 *************************************************************************
 
 The same mentioned for calendars is valid for addressbooks as well.
 
 Synchronizing calendars ( i.e. files ) means, 
 to merge two calendars in a useful way.
 If the two calendars are completely different, 
 there is no problem, the resulting calendar contains 
 all data from the local and from the remote calendar.
@@ -232,25 +281,59 @@ SYNC PREFERENCES:
   is automatically set as default button.
   The color for the newest entry is green.
 
  -Force: Take local entry always:
   Even if the calendars are already synced
   there is no item deleted on local. 
 
  -Force: Take remote entry always:
   Analogous to  
   "Force: Take local entry always"
 
 *************************************************************************
-5) Details about sync profile kinds
+5) How a filter works
+*************************************************************************
+
+A filter is a rule to decide if a particular item
+(calendar iten item or contact item) belongs to a set of items.
+For example, you can specify a set as:
+Only items, that belongs to that category.
+Or: Only items, that does not belong to that category.
+Or: Only items, that are public.
+
+If you specify a filter in a syncing profile, you can set the
+rules of adding items to the local or remote database.
+
+Example:
+You have a public calendar in your company, which contains all
+company relevant data.
+
+You have different projects in the company and for project specific events
+is always set the project name as a category: 
+E.g. all events of the project PRO_ABC do have set the categorie PRO_ABC.
+But you are not interested in events of PRO_ABC, because you are not working on it.
+Then you can specify a filter: All, but not with categoroy PRO_ABC.
+When you specify this filter as an incoming filter for your sync profile,
+all events of the company are synced and added to your local calendar, but not
+the evenst of the project PRO_ABC.
+
+You do not want that your private data can be seen 
+in the public calendar of your company.
+Well, set the property to "private" for all your private data 
+and specify an outgoing filter: Only " public" and "confidential".
+Then you can sync your personal calendar with the calendar of the company,
+but your private data is not added to the public calendar. 
+ 
+*************************************************************************
+6) Details about sync profile kinds
 *************************************************************************
 
 a) Local file
    Please specify a local file you want to sync with.
    Note:  If you are syncing a file, which is used by KA/Pi, please check the
           "Addressbook file (*.vcf) is used by KA/Pi".
           If you are syncing with a file from KAddressbook or another program, 
           please uncheck "Addressbook file (*.vcf) is used by KA/Pi".
           To set this properly is important! KA/Pi uses a "last modified" property, 
           which is not supported by KAddressbook.
 
 b) Pi-Sync (direct Kx/Pi to Kx/Pi sync)