On 02/04/14 13:16, Patrick Ohly wrote: > FWIW, here's the terminology section from the README. It's meant to > introduce concepts from scratch, i.e. nothing should depend on anything > not defined yet.
I appreciate the effort that has gone into this: I have read it many times, and I even had it to hand while writing my earlier reply to Emile. But I have to say that it has never helped me as much as I would like :-) I realise this is my failing, but I have always found it very hard to understand what is going on with these. I am getting better as I do more, but I have been using SE for quite a while now and still am lost with configuration half the time. What we really need, I think, are more tutorial materials, not just definition materials. Maybe, one day, we will find a technical writer with some spare time who can make a contribution. One thing which may have been not ideal, with hindsight, is to have everything configured with one single command (--configure) which gives no hint to the class of the object being configured (let alone the scope of the attribute being set: shared/unshared). Leaving it up to the user to understand the niceties of command line object naming to work out what sort of thing is being configured is a task that requires a high level of experience and is frustrating for a newbie. Is it worth considering introducing new --configure commands such as --configure-context, --configure-source, --configure-peer (and deprecating --configure)? The new commands would work exactly the same way as the current --configure except they would check that the thing you were configuring actually was of the expected type? I also find the (well-intentioned) defaulting causes me more confusion -- templates, default context, target-config are powerful tools but are of much more use for the expert, I feel, than the beginner. I try to avoid them. I would very much welcome being able to specify a context in the local: URL and discard all my use of target-config. A couple of specific points: > local/remote > Synchronization always happens between a pair of databases and thus > has two sides. One database or side of a sync is remote (the one > of the peer) or local (SyncEvolution). For the sake of consistency (and > lack of better terms), these terms are used even if the peer is another > instance of SyncEvolution and/or all data resides on the same storage. It would be helpful (if they are true!) to add a couple of points: In all cases, the local database is the one named in the sync command line, the remote database is the one referenced in the syncUrl property. Note that local/remote is independent of client/server. > sync config > A sync configuration defines how to access a peer: the protocol > which is to be used, how to find the peer, credentials, etc. Peers > might support more than one protocol, in which case multiple > sync configs have to be created. Maybe delete the last sentence: not sure it adds any very important information. Surely the more usual reason for creating multiple sync configs is that you have multiple devices to sync? > source config > Each data source corresponds to a local database. A source config > defines how to access that database, like a sync config does for > peers. This information about a local database is independent > of the peers that the database might be synchronized with. > > Sync configs use these shared source configs and add additional, > per-peer settings to each of them that define how that local > database maps to a remote database in the peer. By default a source > config is inactive inside a sync config and thus ignored. It must be > activated by setting the unshared `sync` property to something other > than `none` (aka `disabled`). This paragraph is very confusing. In what sense is a source config "inside" a sync config? Maybe the second and third sentences could be replaced with something like: The sync config ignores source configs in the same context unless the "sync" property for the source is set to something other than "none" (aka "disabled"). > configuration property > Sync and source configs contain configuration properties. Each > property is a name/value pair. Sync properties are used in sync configs, > source properties in source configs. The names were chosen so that > they are unique, i.e., no sync property has the same name as a source > property. > > A property can be *unshared* (has separate values for each peer, therefore > sometimes also called *per-peer*; for example the `uri` property which > defines the remote database), *shared* (same value for all peers; for > example the `database` property for selecting the local database) or > *global* (exactly one value). I have found this confusing as well. To the naive view, per-peer properties should be sync properties, shared properties should be source properties, and global properties should be context properties. > context > Sync and source configs are defined inside a configuration context. > Typically each context represents a certain set of sources. The values > of shared properties are only shared inside their context. That way > it is possible to define a second `work` context with a `work calendar` > source using one database and use the implicit `default` context for > a private `calendar` source with a different database. The second sentence is why I tend to view a context as a source. I realise it is different from the per-folder/collection/database... meaning of source, but I think of the context as defining the "source of the data". > local sync > Traditionally, a sync config specifies SyncML as the synchronization > protocol. The peer must support SyncML for this to work. When the > peer acts as SyncML server, conflict resolution happens on the > peer, outside of the control of SyncEvolution. Is there some reason conflict resolution gets mentioned here? Does it really have anything to do with local sync? > In a so called `local sync`_, SyncEvolution connects two of its own > backends and runs all of the synchronization logic itself on the host. Again, why mention synchronization? Is there something important you are trying to convey? In what way is local sync actually any different from defining two SyncML peers (in different contexts) and connecting them together? In fact, I have often thought of doing that (to try to avoid the confusing special cases involved in local sync). The only thing stopping me is that I wasn't sure SyncEvolution could handle multiple (apparently completely independent) syncs happening at the same time (in different contexts). Graham _______________________________________________ SyncEvolution mailing list [email protected] https://lists.syncevolution.org/mailman/listinfo/syncevolution
