Patrick, 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.
--Todd ================ item The smallest unit of synchronization. Examples of items include calendar events and individual contacts, memos, or tasks. database 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. context 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. host The device or computer on which SyncEvolution runs. peer 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 databases). backend 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 "keyring". * 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 "sync" and "source" properties. * 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. Regards, --Todd Todd Wilson, PhD Department of Computer Science California State University, Fresno On Tue, Apr 15, 2014 at 2:36 AM, Patrick Ohly <[email protected]> wrote: > Hello! > > 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 > "sync config". > * 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 > section. > * 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 > additional properties. > * 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 > yet how. > > 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. > > _______________________________________________ SyncEvolution mailing list [email protected] https://lists.syncevolution.org/mailman/listinfo/syncevolution
