Re: [SyncEvolution] documentation update, enhanced command line

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 <patrick.ohly(a)intel.com&gt; wrote: