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.