Thanks for your efforts at clarifying the documentation. For me, as a
newcomer, the most important part of the documentation is the
terminology section, since it sets the context in which the rest of
the document can be understood (or not understood!). If I -- despite
being a newcomer -- were asked to edit this section to make it easier
for *me* to understand, what I'd come up with would look something
like what follows. I've tried to simplify/unify the concepts as much
as I could, and have taken the liberty of changing some terminology
that I found confusing (with apologies now, in advance), but I'm sure
I've made some bad guesses about the details, and my relative
ignorance of SyncEvolution will no doubt be obvious. This wasn't meant
to be complete, but only what I had the "steam" to write out now;
nevertheless, I hope you find this exercise useful.
The smallest unit of synchronization. Examples of items include
calendar events and individual contacts, memos, or tasks.
A collection of items. Databases are what SyncEvolution keeps
synchronized. Every synchronization involves two databases and can be
one-way as well as two-way, so we distinguish the two sides of a
synchronization by calling them the source and the target. Examples of
databases include a Google calendar or task list, a particular phone's
address book, a local copy of one of these in a computer's filesystem,
or a collection of items that SyncEvolution is making available to
clients in its capacity as a server.
A collection of databases. Databases are groups together in contexts
to facilitate configuration. A database may be in more than one
context, but If two databases are to be synchronized, they must be in
the same context. Contexts have names that begin with '@', and there
is a default context, called @default, that is used when no specific
context is given.
The device or computer on which SyncEvolution runs.
An entity that stores one or more databases and makes them available
to clients through a protocol such as SyncML, ActiveSync, CalDAV, or
CardDAV. This can be another device (like a phone), a server (like
Google), or the host itself (when we want to synchronize two local
An implementation of the methods used to read, add, update, and
remove items from/to/in a database. When used in connection with
specific configuration properties (see below), the backend provides a
uniform interface to the database that can be used independently of
the peer that stores it or the protocol that must be used to access it
on the peer.
configuration properties (or just "properties")
Key/value pairs used to specify some aspect of how SyncEvolution
behaves. Because SyncEvolution has several different but overlapping
functions that need to be configured, properties are organized into a
hierarchy of "configurations" so that they can be appropriately
shared. The hierarchy of these configurations (and where they are
stored) is as follows:
* global config (~/.config/syncevolution/config.ini): this contains
properties that apply to SyncEvolution as a whole, for example
* context configs, one for each context
(~/.config/syncevolution/<context name>/config.ini): these contain the
properties that are shared among all databases in a context (and their
associated peers), for example "logdir".
* peer configs, one for each context/peer combination
(~/.config/syncevolution/<context name>/peers/<peer name>/config.ini):
these contain the properties associated with each peer storing
databases in the context, for example "syncURL".
* store configs, one for each database in a context and its associated
peer (~/.config/syncevolution/<context name>/peers/<peer
name>/sources/<source name>/config.ini): these are the parameters
needed specify how to access a specific database, for example
"backend" and "database".
Notes on the above:
* I couldn't see why shared source properties were needed, since a
source is always associated to a unique peer, so I didn't include a
configuration for that. I imagine that they could just be merged into
what I called the store config.
* I preferred "store" over "source", since sources are not just
sources of data but also targets of data.
* I preferred a hierarchy of configurations to calling properties
"shared" or "unshared", or making a distinction between
* I don't think a separate mention of "local sync" is necessary. The
main difference seems to be the synchronization logic, but it can be
explained, without introducing new terminology, that SyncEvolution is
responsible for this logic when both databases are on the host.
Todd Wilson, PhD
Department of Computer Science
California State University, Fresno
On Tue, Apr 15, 2014 at 2:36 AM, Patrick Ohly <patrick.ohly(a)intel.com> wrote:
The "Getting the concepts clear" mail thread and a private email
exchange with Todd identified several shortcomings in the documentation
and/or implementation. This is my attempt to address those. A diff and
the full modified README.rst are attached.
Some of these changes will require changes in the implementation.
In short, what I am trying to achieve is:
* Better explain what local sync is and how it involves two sync
configs. "originating config" gets introduces instead of just
* Better explain the relationship between contexts, sync configs,
and source configs ("a sync config can use the source configs in
the same context").
* An entire section on config properties in the terminology
* Less focus on conflict resolution, as suggested by Graham.
* Remove the hard-coded "target-config" name. It still needs to be
there as fallback for existing configs or users continuing to
use the current instructions.
* Fix examples that became invalid when fixing the password
storage/lookup mechanism for GNOME keyring in 1.4. I noticed
that the username=email-address part should be handled without
* Fix WebDAV with DNS auto-discovery. Few servers support it, so
this hasn't been noticed before.
* Fix the implicit command line magic where it does some
consistency checks when creating new configs. Not exactly sure
I ran out of stream after updating the terminology section, the "command
line conventions", "Synchronization beyond SyncML" and "CalDAV and
CardDAV". It's possible that the other sections also contain slightly
incorrect usage of the terminology or are simply out-dated.
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.