On Fr, 2011-01-07 at 14:12 +0000, Patrick Ohly wrote: > On that occasion I also want to make several other changes which will > prevent going back: > 1. split "type" into independent options, to solve > http://bugs.meego.com/show_bug.cgi?id=1023
Implemented. Below is the commit message (which explains the changes) and the new help texts. The old "sync" help text is also quoted, for comparison. Are the help texts useful? Any suggestions how to improve them? This is a fairly intrusive change. On the other hand, the existing tests cover many aspects of it pretty well. I'll release a 1.1.99.x snapshot soon and hope that some adventurous users will update to that version. I'll do the same ;-} ----------------------------------------- commit 388f72b369708895327b4d18a3c6fd6cfd86305d Author: Patrick Ohly <[email protected]> Date: Thu Feb 3 12:17:24 2011 +0100 config: replaced overloaded "type" with "backend/databaseFormat/syncFormat/forceSyncFormat" (BMC #1023) The meaning of "type" was horribly complex and had effects on the backend and the peer. It was impossible to specify the sync format to be used for a specific peer independently of the local backend and its format, so adding a peer to a context broke the context configuration (BMC #1023). This is now fixed by splitting "type" into four independent properties: - backend = plugin which interfaces with the data - databaseFormat = data format used inside backend, only relevant for file backend - syncFormat = data format preferred when talking to peer - forceSyncFormat = disable format auto-negotiation, use preferred format With that split, it is now possible to specify the format in which the file backend stores items independently of the format in which they are exchanged with the peer. Old configurations with "type" can still be read. The values specified inside it are transparently mapped to the new properties. Command line and D-Bus API users will only see the new properties. The command line tool still accepts "type" as an alias for the four new properties. Using that has the same disadvantage as before: it will modify the context even if only modifying the peer was intended. The D-Bus API accepts only the new properties. Clients using "type" must be adapted to the new property names. Clients not using that continue to run unchanged. Writing into the configuration requires a migration of the peer config *and* the context in which it is defined. That is necessary because the new semantic (independent database format) cannot be stored in the old format. The migration is handled by rewriting first the context, then all peers defined inside it. Other user-visible changes: - updated help texts - the canonical "backend" value for the file backend is just "file" instead of the long "Files in one directory", which is now an alias (used to be the other way around); done because "type = file" was expanded to the long name, which was a bit unexpected and showed how unintuitive the long name is ------------------------------------------------------------ $ syncevolution --source-property ? [...] backend: Specifies the SyncEvolution backend and thus the data which is synchronized by this source. Each backend may support multiple databases (see 'database' property), different formats inside that database (see 'databaseFormat'), and different formats when talking to the sync peer (see 'syncFormat' and 'forceSyncFormat'). A special 'virtual' backend combines several other data sources and presents them as one set of items to the peer. For example, Nokia phones typically exchange tasks and events as part of one set of calendar items. Right now such a virtual backend is limited to combining one calendar source with events and one task source. They have to be specified in the 'database' property, typically like this: calendar,todo Different sources combined in one virtual source must have a common format. As with other backends, the preferred format can be influenced via the 'syncFormat' attribute. Here's the full list of potentially supported backends, valid 'backend' values for each of them, and possible formats. Note that SyncEvolution installations usually support only a subset of the backends; that's why e.g. "addressbook" is unambiguous although there are multiple address book backends. Currently active: Evolution Address Book = Evolution Contacts = addressbook = contacts = evolution-contacts vCard 2.1 (default) = text/x-vcard vCard 3.0 = text/vcard The later is the internal format of Evolution and preferred with servers that support it. Evolution Calendar = calendar = events = evolution-events iCalendar 2.0 (default) = text/calendar vCalendar 1.0 = text/x-vcalendar Evolution Task List = Evolution Tasks = todo = tasks = evolution-tasks iCalendar 2.0 (default) = text/calendar vCalendar 1.0 = text/x-vcalendar Evolution Memos = memo = memos = evolution-memos plain text in UTF-8 (default) = text/plain iCalendar 2.0 = text/calendar vCalendar 1.0 = text/x-vcalendar The later format is not tested because none of the supported SyncML servers accepts it. Files in one directory = file Stores items in one directory as one file per item. The directory is selected via database=[file://]<path>. It will only be created if the prefix is given, otherwise it must exist already. The database format *must* be specified explicitly. It may be different from the sync format, as long as there are conversion rules (for example, vCard 2.1 <-> vCard 3.0). If the sync format is empty, the database format is used. Examples for databaseFormat + syncFormat: text/plain + text/plain text/x-vcard + text/vcard text/calendar Examples for evolutionsource: /home/joe/datadir - directory must exist file:///tmp/scratch - directory is created Currently inactive: mkcal = KCalExtended = calendar 'database' normally is the name of a calendar inside the default calendar storage. If it starts with the 'SyncEvolution_Test_' prefix, it will be created as needed, otherwise it must exist. If it starts with the 'file://' prefix, the default calendar in the specified SQLite storage file will created (if needed) and used. Maemo Calendar = calendar = events = maemo-events iCalendar 2.0 (default) = text/calendar vCalendar 1.0 = text/x-vcalendar Maemo Tasks = todo = tasks = maemo-tasks iCalendar 2.0 (default) = text/calendar vCalendar 1.0 = text/x-vcalendar Maemo Notes = memo = memos = notes = journal = maemo-notes plain text in UTF-8 (default) = text/plain iCalendar 2.0 = text/calendar vCalendar 1.0 = text/x-vcalendar QtContacts = addressbook = contacts = qt-contacts vCard 3.0 = text/vcard SQLite Address Book = addressbook = contacts = sqlite-contacts vCard 2.1 (default) = text/x-vcard XMLRPC interface = xmlrpc Data exchange is done via an XMLRPC interface on the datastore. Mac OS X or iPhone Address Book = addressbook = contacts = apple-contacts syncFormat: When there are alternative formats for the same data, each side of a sync offers all that it supports and marks one as preferred. If set, this property overrides the format that would normally be marked as preferred by a backend. Valid values depend on the backend. Here are some examples: contacts - text/vcard = vCard 3.0 format text/x-vcard = legacy vCard 2.1 format calendar - text/calendar = iCalendar 2.0 format text/x-vcalendar = legacy vCalendar 1.0 format Errors while starting to sync and parsing and/or storing items on either client or server can be caused by a mismatch between the sync format and uri at the peer. forceSyncFormat: Some peers get confused when offered multiple choices for the sync format or pick the less optimal one. In such a case, setting this property enforces that the preferred format specified with 'syncFormat' is really used. databaseFormat: Defines the data format to be used by the backend for its own storage. Typically backends only support one format and ignore this property, but for example the file backend uses it. See the 'backend' property for more information. [...] ---------------------------------------------------------------- type: Specifies the SyncEvolution backend and thus the data which is synchronized by this source. Some backends can exchange data in multiple formats. Some of them have a default format that is used automatically unless specified differently. Sometimes the format must be specified. This property can be set for individual peers as well as for the context. Different peers in the same context can use different formats, but the backend must be consistent. A special 'virtual' backend combines several other data sources and presents them as one set of items to the peer. For example, Nokia phones typically exchange tasks and events as part of one set of calendar items. Right now such a virtual backend is limited to combining one calendar source with events and one task source. They have to be specified in the 'evolutionsource' property, typically like this: calendar,todo In all cases the format of this configuration is <backend>[:format][!] Different sources combined in one virtual source must have a common representation. As with other backends, the preferred format can be influenced via the 'format' attribute. When there are alternative formats for the same data, each side offers all that it supports and marks one as preferred. The other side then picks the format that it uses for sending data. Some peers get confused by this or pick the less suitable format. In this case the trailing exclamation mark can be used to configure exactly one format. Here are some valid examples: contacts - synchronize address book with default vCard 2.1 format contacts:text/vcard - address book with vCard 3.0 format calendar - synchronize events in iCalendar 2.0 format calendar:text/x-vcalendar - prefer legacy vCalendar 1.0 format calendar:text/calendar! - allow only iCalendar 2.0 virtual:text/x-vcalendar - a virtual backend using vCalendar 1.0 format Errors while starting to sync and parsing and/or storing items on either client or server can be caused by a mismatch between type and uri. Here's the full list of potentially supported backends, valid <backend> values for each of them, and possible formats. Note that SyncEvolution installations usually support only a subset of the backends; that's why e.g. "addressbook" is unambiguous although there are multiple address book backends. Currently active: Evolution Address Book = Evolution Contacts = addressbook = contacts = evolution-contacts vCard 2.1 (default) = text/x-vcard vCard 3.0 = text/vcard The later is the internal format of Evolution and preferred with servers that support it. One such server is ScheduleWorld together with the "card3" uri. Evolution Calendar = calendar = events = evolution-events iCalendar 2.0 (default) = text/calendar vCalendar 1.0 = text/x-vcalendar Evolution Task List = Evolution Tasks = todo = tasks = evolution-tasks iCalendar 2.0 (default) = text/calendar vCalendar 1.0 = text/x-vcalendar Evolution Memos = memo = memos = evolution-memos plain text in UTF-8 (default) = text/plain iCalendar 2.0 = text/calendar vCalendar 1.0 = text/x-vcalendar The later format is not tested because none of the supported SyncML servers accepts it. Files in one directory = file Stores items in one directory as one file per item. The directory is selected via evolutionsource=[file://]<path>. It will only be created if the prefix is given, otherwise it must exist already. Only items of the same type can be synchronized and this type must be specified explicitly with both mime type and version. Examples for type: file:text/plain:1.0 file:text/x-vcard:2.1 file:text/vcard:3.0 file:text/x-vcalendar:1.0 file:text/calendar:2.0 Examples for evolutionsource: /home/joe/datadir - directory must exist file:///tmp/scratch - directory is created ------------------------------------------------------------------------ -- Best Regards, Patrick Ohly The content of this message is my personal opinion only and although I am an employee of Intel, the statements I make here in no way represent Intel's position on the issue, nor am I authorized to speak on behalf of Intel on this matter. _______________________________________________ SyncEvolution mailing list [email protected] http://lists.syncevolution.org/listinfo/syncevolution
