Re: [SyncEvolution] documentation update, enhanced command line

On Tue, 2014-04-15 at 20:56 -0700, Todd Wilson wrote: > 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. 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. > ================ > item > The smallest unit of synchronization. Examples of items include > calendar events and individual contacts, memos, or tasks. Good point, that was missing. > database > 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"). Using "source" is difficult because it gets used also outside of a synchronization. > 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. > context > A collection of databases. Databases are groups together in contexts > to facilitate configuration. A database may be in more than one > context, 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 > "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". 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 that. > * 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 "store". > * I preferred a hierarchy of configurations to calling properties > "shared" or "unshared", or making a distinction between "sync" and > "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 command line. > * 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.