I'll revise and expand my personal version of the README based on the
comments you've given and repost. As I expected, there were several
aspects of SyncEvolution I was only partially understanding, and I'll
try to read through the documentation again with your comments in
mind. Since my main conceptual misunderstanding concerned the
relationship between databases and peers, could you give some extra
explanation and perhaps examples to help me out? Thanks,
Todd Wilson, PhD
Department of Computer Science
California State University, Fresno
On Wed, Apr 16, 2014 at 1:17 AM, Patrick Ohly <patrick.ohly(a)intel.com> wrote:
On Tue, 2014-04-15 at 20:56 -0700, Todd Wilson wrote:
> 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.
It is useful, thanks. As Ove did when giving his summary of how
SyncEvolution's local sync works, it tells me how it is perceived by
others and where misunderstandings are. I'll probably pick some portions
that I find better than my own attempts.
> The smallest unit of synchronization. Examples of items include
> calendar events and individual contacts, memos, or tasks.
Good point, that was missing.
> A collection of items. Databases are what SyncEvolution keeps
> synchronized. Every synchronization involves two databases
Depends on the meaning of "synchronization". If it is a sync session,
then more than two databases can be involved at once. What is meant here
is that databases always get synchronized in pairs.
> 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.
Which one is which? My own attempt is based on where the sync is
triggered form the perspective of the user ("local" and "remote").
"source" is difficult because it gets used also outside of a
> Examples of
> databases include a Google calendar or task list,
A minor nitpick: Google doesn't have task lists, do they?
> 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.
The "collection of items" probably should be "collection of items in a
filesystem directory". Otherwise it's giving an example by quoting the
definition (database = collection of items). This is not limited to
running as server.
> A collection of databases. Databases are groups together in contexts
> to facilitate configuration. A database may be in more than one
Is this the existing "context" concept? It is possible to define access
to the same database in different contexts, but that is not common.
> but If two databases are to be synchronized, they must be in
> the same context.
Not in the current "context" concept. The common case is that one
database is on the host and the other is on some remote peer (SyncML
sync), or one database is access via one context and the other via
another (traditional local sync). Allowing both databases in the same
context was only allowed recently in 1.4, and is not required.
> 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".
I find it misleading to say "peer storing databases in the context". The
databases are not created by the peer, they get accessed by it.
> * 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.
Here you are overlooking a key concept: databases are not necessarily
associated with a unique peer. First you have databases and the
definition of how to access them, then you add peers that use the
databases. The shared source properties that you dropped above are used
to define this per-independent access.
What you think of is a narrower use case, where a new database is
created for each database on the peer. SyncEvolution is not limited to
> * I preferred "store" over "source", since sources are not just
> sources of data but also targets of data.
I can live with that name change. The term "source" came from the
Funamol SyncML engine, whereas the current Synthesis engine also uses
> * I preferred a hierarchy of configurations to calling properties
> "shared" or "unshared", or making a distinction between
> "source" properties.
Indeed, it might make sense to introduce the hierarchy first, then
explain how it maps to the sync and source properties as used by the
> * 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.
I had it in the terminology section because local sync introduces its
own terms, "originating and target config", and those can't be
documented in the terminology section without also describing local
sync. I still find that relevant.
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.