9:36 a.m.
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.
9:55 a.m.
Sorry, I didn't see this before sending out my latest email. I'll read
through this to see where I ought to update.
Regards,
Emile
On 15/04/2014 11:36:27, "Patrick Ohly" <patrick.ohly(a)intel.com> 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.
3:56 a.m.
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> 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.
8:17 a.m.
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.
3:56 p.m.
I'll revise and expand my personal version of the README based on the
comments you've given and repost. As I expected, there were several
aspects of SyncEvolution I was only partially understanding, and I'll
try to read through the documentation again with your comments in
mind. Since my main conceptual misunderstanding concerned the
relationship between databases and peers, could you give some extra
explanation and perhaps examples to help me out? Thanks,
--Todd
Todd Wilson, PhD
Department of Computer Science
California State University, Fresno
On Wed, Apr 16, 2014 at 1:17 AM, Patrick Ohly <patrick.ohly(a)intel.com> wrote:
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.
4:42 p.m.
On Wed, 2014-04-16 at 08:56 -0700, Todd Wilson wrote:
I'll revise and expand my personal version of the README based on
the
comments you've given and repost. As I expected, there were several
aspects of SyncEvolution I was only partially understanding, and I'll
try to read through the documentation again with your comments in
mind. Since my main conceptual misunderstanding concerned the
relationship between databases and peers, could you give some extra
explanation and perhaps examples to help me out?
I am not sure what additional explanation I can give beyond what was
already said in the mail threads and in the revised README.
Some examples can be found in the HOWTO on the item manipulation
operations:
https://syncevolution.org/wiki/item-operations
This mostly just passes the required properties on the command line, but
all of the examples also work if you do a "--configure @somecontext
somesource" with the properties first and the just use "@somecontext
somesource" at the end of the command line.
--
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.
5:43 p.m.
I really do think my latest version captures the major concepts and the
basic useful operations you can perform on them. It's laced with examples -
if I got this iteration right, my next step is to rewrite the other how-tos
in that vein.
More specifically, I think we need to converge, not diverge the
terminology. I *have* diverted from the existing syncevolution terminology
where I think they suggest commonality where there is none; perhaps the
technical implementation of the configuration of target-config and sync
config share code, but if my understanding of them is correct, their
behavior is non-trivially different, and that I have reflected in new
naming.
I am in no way specifically enamored by the new names I introduced, and
I'll gladly swap them for others, but to have 3 sets of terms in play is
not going to be helpful I think.
Emile
On Apr 16, 2014 6:42 PM, "Patrick Ohly" <patrick.ohly(a)intel.com> wrote:
On Wed, 2014-04-16 at 08:56 -0700, Todd Wilson wrote:
> I'll revise and expand my personal version of the README based on the
> comments you've given and repost. As I expected, there were several
> aspects of SyncEvolution I was only partially understanding, and I'll
> try to read through the documentation again with your comments in
> mind. Since my main conceptual misunderstanding concerned the
> relationship between databases and peers, could you give some extra
> explanation and perhaps examples to help me out?
I am not sure what additional explanation I can give beyond what was
already said in the mail threads and in the revised README.
Some examples can be found in the HOWTO on the item manipulation
operations:
https://syncevolution.org/wiki/item-operations
This mostly just passes the required properties on the command line, but
all of the examples also work if you do a "--configure @somecontext
somesource" with the properties first and the just use "@somecontext
somesource" at the end of the command line.
--
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.
8:05 p.m.
On Wed, 2014-04-16 at 19:43 +0200, Emiliano Heyns wrote:
More specifically, I think we need to converge, not diverge the
terminology. I *have* diverted from the existing syncevolution
terminology where I think they suggest commonality where there is
none; perhaps the technical implementation of the configuration of
target-config and sync config share code, but if my understanding of
them is correct, their behavior is non-trivially different, and that I
have reflected in new naming.
I am in no way specifically enamored by the new names I introduced,
and I'll gladly swap them for others, but to have 3 sets of terms in
play is not going to be helpful I think.
I agree, we need to agree on updated terminology and (where necessary)
functional changes before we can adapt HOWTOs. The problem with the
HOWTOs is (and always has been) that many users will be on SyncEvolution
1.4 or even older for a while to come.
Any new HOWTO depending on new functionality will have to be very
explicit about the version of SyncEvolution that it depends on, and we
cannot remove the "old" content that it replaces right away.
Regarding converging: we can follow two approaches or perhaps phases.
First we reach consensus on key terms. Contentious (or at least not
explicitly accepted) are:
* "originating source" in a local sync (proposed by me).
* "source" vs. "store" (I think both Todd and Emile preferred
store).
* "Client Endpoints" instead of "sync configs" (Emile)
* "Synced stores" as new term for the per-peer source properties
(Emile)
The next phase then would be to pick the exact wording for README.rst,
using these agreed terms. We should do this using git commits in actual
repos, to facilitate merging and change tracking. If someone wants to
propose new text for the README.rst, please clone the new "doc" branch
in http://cgit.freedesktop.org/SyncEvolution/syncevolution/?h=doc and
post patches in "git format-patch" style to the list. Optionally also
push the updated git tree somewhere (github?), in particular if it
involves merges.
I've push my own proposal there, but it is not final because I think I
will pick up more of your proposals once their is consensus on terms.
Regarding the new terms, here's my position:
+1 for "originating source". I think it is needed.
+1 for "store" instead of "source". I agree with Todd's
explanation that
the source incorrectly implies a data direction.
-1 for "Client Endpoints". This is misleading because the same thing is
also needed for servers. "sync config" covers both because it is
neutral.
-1 "Synced stores". This just doesn't sound right to me, but I cannot
quite nail why. Perhaps because I simply don't think of this as real
entities, just as some additional settings for a source (or soon,
store).
--
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.
8:18 p.m.
On Wed, Apr 16, 2014 at 1:05 PM, Patrick Ohly <patrick.ohly(a)intel.com>wrote:
On Wed, 2014-04-16 at 19:43 +0200, Emiliano Heyns wrote:
> More specifically, I think we need to converge, not diverge the
> terminology. I *have* diverted from the existing syncevolution
> terminology where I think they suggest commonality where there is
> none; perhaps the technical implementation of the configuration of
> target-config and sync config share code, but if my understanding of
> them is correct, their behavior is non-trivially different, and that I
> have reflected in new naming.
I agree that terminology (and concepts) should come first. One thing I was
attempting to do with my post was to find a minimal set of
terminology/concepts that would suffice to explain what SE does and then
introduce it in a "cumulative" way with a minimum of forward references,
the same way that mathematical texts or formal specifications proceed. That
reduces the burden on someone trying to understand SE by giving them a path
through the concepts that they can follow from beginning to end. I realize
that that will not always be possible, but I think it should be a goal.
Regarding converging: we can follow two approaches or perhaps phases.
First we reach consensus on key terms. [...]
The next phase then would be to pick the exact wording for README.rst,
using these agreed terms. We should do this using git commits in actual
repos, to facilitate merging and change tracking. [...]
+1 and +1
Regarding the new terms, here's my position:
+1 for "originating source". I think it is needed.
+1 for "store" instead of "source". I agree with Todd's
explanation that
the source incorrectly implies a data direction.
-1 for "Client Endpoints". This is misleading because the same thing is
also needed for servers. "sync config" covers both because it is
neutral.
-1 "Synced stores". This just doesn't sound right to me, but I cannot
quite nail why. Perhaps because I simply don't think of this as real
entities, just as some additional settings for a source (or soon,
store).
I want to do more work trying to understand SE as it is before I offer my
position. I've been reading Emiliano's helpful document, and will keep
making passes through that and your README until my understanding
converges. Then I'll see if I can document that understanding in a
"cumulative" way, starting from first principles, with a minimum of forward
references.
--Todd
8:21 p.m.
------ Original Message ------
From: "Patrick Ohly" <patrick.ohly(a)intel.com>
To: "Emiliano Heyns" <emiliano.heyns(a)iris-advies.com>
Cc: "Todd Wilson" <twilson(a)csufresno.edu>; "Graham Cobb"
<g+syncevolution(a)cobb.uk.net>; "SyncEvolution"
<syncevolution(a)syncevolution.org>; "Ove Kåven" <ovek(a)arcticnet.no>
Sent: 16-4-2014 22:05:27
Subject: Re: documentation update, enhanced command line
First we reach consensus on key terms. Contentious (or at least not
explicitly accepted) are:
* "originating source" in a local sync (proposed by me).
* "source" vs. "store" (I think both Todd and Emile preferred
store).
* "Client Endpoints" instead of "sync configs" (Emile)
* "Synced stores" as new term for the per-peer source properties
(Emile)
The next phase then would be to pick the exact wording for README.rst,
using these agreed terms. We should do this using git commits in actual
repos, to facilitate merging and change tracking. If someone wants to
propose new text for the README.rst, please clone the new "doc" branch
in http://cgit.freedesktop.org/SyncEvolution/syncevolution/?h=doc and
post patches in "git format-patch" style to the list. Optionally also
push the updated git tree somewhere (github?), in particular if it
involves merges.
All for this.
I've push my own proposal there, but it is not final because I think I
will pick up more of your proposals once their is consensus on terms.
Regarding the new terms, here's my position:
+1 for "originating source". I think it is needed.
I'm perfectly fine
with this. I currently understand this to cover, a.o.
a server-initiated sync as implemented in the target-config setup. I'll
go through the README.rst again and update my explanation accordingly.
+1 for "store" instead of "source". I agree with Todd's
explanation
that
the source incorrectly implies a data direction.
Agreed.
-1 for "Client Endpoints". This is misleading because the same thing is
also needed for servers. "sync config" covers both because it is
neutral.
I am entirely open to ditching client endpoints. I feel iffy about
'sync
config' because it is so generic; it doesn't really disclose anything
except 'it does something with sync' -- but then, everything of
syncevolution does something with sync.
-1 "Synced stores". This just doesn't sound right to me,
but I cannot
quite nail why. Perhaps because I simply don't think of this as real
entities, just as some additional settings for a source (or soon,
store).
I hate the term myself, so no complaints on replacing it. If it stays as
a property of a store (BTW, this was explained earlier as a property of
the "sync config", not the store), the best way to describe it would be
"a dictionary of which the keys must exist as a store in the same
context". As the keys of this dictionary have constraints, and the
values of this dictionary have properties that depend on them, I think
their behavior is complex enough to warrant existence. Specifically, the
matching that happens in the setup of target-config et al gets confusing
if we deny these exist.
Regards,
Emile
9:01 a.m.
On Wed, 2014-04-16 at 20:21 +0000, Heyns Emiliano wrote:
>Regarding the new terms, here's my position:
>
>+1 for "originating source". I think it is needed.
I'm perfectly fine with this. I currently understand this to cover, a.o.
a server-initiated sync as implemented in the target-config setup. I'll
go through the README.rst again and update my explanation accordingly.
>
>+1 for "store" instead of "source". I agree with Todd's
explanation
>that
>the source incorrectly implies a data direction.
Agreed.
>
>-1 for "Client Endpoints". This is misleading because the same thing is
>also needed for servers. "sync config" covers both because it is
>neutral.
I am entirely open to ditching client endpoints. I feel iffy about 'sync
config' because it is so generic; it doesn't really disclose anything
except 'it does something with sync' -- but then, everything of
syncevolution does something with sync.
"sync config" has to be fairly generic, because sync configs are used
for all kinds of things:
* Syncing with SyncML clients.
* Syncing with SyncML clients.
* The two sides in a local sync.
* To store username/password once for several other sync or source
configs (see "id:<name of config with credentials>" in the NEWS
file).
Suggestions for a better name are welcome.
>-1 "Synced stores". This just doesn't sound right
to me, but I cannot
>quite nail why. Perhaps because I simply don't think of this as real
>entities, just as some additional settings for a source (or soon,
>store).
I hate the term myself, so no complaints on replacing it. If it stays as
a property of a store (BTW, this was explained earlier as a property of
the "sync config", not the store), the best way to describe it would be
"a dictionary of which the keys must exist as a store in the same
context". As the keys of this dictionary have constraints, and the
values of this dictionary have properties that depend on them, I think
their behavior is complex enough to warrant existence. Specifically, the
matching that happens in the setup of target-config et al gets confusing
if we deny these exist.
I'm fine with introducing a separate term for this, but it needs to be
something that fits. My own best idea was and still is "per-peer store
properties".
--
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.
9:58 a.m.
On 17/04/2014 11:01:24, "Patrick Ohly" <patrick.ohly(a)intel.com> wrote:
I am entirely open to ditching client endpoints. I feel iffy about
'sync
> config' because it is so generic; it doesn't really disclose anything
> except 'it does something with sync' -- but then, everything of
> syncevolution does something with sync.
"sync config" has to be fairly generic, because sync configs are used
for all kinds of things:
* Syncing with SyncML clients.
* Syncing with SyncML clients.
* The two sides in a local sync.
* To store username/password once for several other sync or
source
configs (see "id:<name of config with credentials>" in the NEWS
file).
But that's the thing. So we have 4 (I guess... one of the first
two
would be "server" yeah?) entirely different concepts, that just happen
to store their properties in a fairly generic dictionary-type object.
What these 4 identifiable things mean is entirely separate from the
implementation detail of how they are stored internally.
Suggestions for a better name are welcome.
I don't think a single name will do.
Much like 'target-config' has a
very specific conceptual meaning that is not covered by the way it
happens to be stored.
I'm fine with introducing a separate term for this, but it needs to be
something that fits. My own best idea was and still is "per-peer store
properties".
I'm fine with that. Are these used for anything but a sync
though?
Emile
2:42 p.m.
On Thu, 2014-04-17 at 09:58 +0000, Emiliano Heyns wrote:
On 17/04/2014 11:01:24, "Patrick Ohly"
<patrick.ohly(a)intel.com> wrote:
> I am entirely open to ditching client endpoints. I feel iffy about
>'sync
>> config' because it is so generic; it doesn't really disclose anything
>> except 'it does something with sync' -- but then, everything of
>> syncevolution does something with sync.
>
>"sync config" has to be fairly generic, because sync configs are used
>for all kinds of things:
> * Syncing with SyncML clients.
> * Syncing with SyncML clients.
> * The two sides in a local sync.
> * To store username/password once for several other sync or
>source
> configs (see "id:<name of config with credentials>" in the
NEWS
> file).
But that's the thing. So we have 4 (I guess... one of the first two
would be "server" yeah?)
Yes, a typo.
entirely different concepts,
I wouldn't call these entirely different concepts. They all provide
information about a peer, so "peer config" looks like suitable generic
term.
As said in the other mail, that does not rule out using more specific
terms where applicable ("a target config is a special peer config").
>I'm fine with introducing a separate term for this, but it
needs to be
>something that fits. My own best idea was and still is "per-peer store
>properties".
I'm fine with that. Are these used for anything but a sync though?
No, not at the moment. I just don't find "sync config" suitable due to
the legacy usage of that term.
--
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.
2:51 p.m.
Conceptually, a server and a client are very different. But I'm not even
looking for sync configs to get different names (even though "peer" would
be more descriptive than "sync config"), but the roles these entities can
play. And for certain the last of the four is conceptually entirely
different; it doesn't configure a sync at all, it is referenced by a peer
which may or may not be present in a peer-pairing.
Emile
On Apr 17, 2014 4:42 PM, "Patrick Ohly" <patrick.ohly(a)intel.com> wrote:
On Thu, 2014-04-17 at 09:58 +0000, Emiliano Heyns wrote:
> On 17/04/2014 11:01:24, "Patrick Ohly" <patrick.ohly(a)intel.com>
wrote:
>
> > I am entirely open to ditching client endpoints. I feel iffy about
> >'sync
> >> config' because it is so generic; it doesn't really disclose
anything
> >> except 'it does something with sync' -- but then, everything of
> >> syncevolution does something with sync.
> >
> >"sync config" has to be fairly generic, because sync configs are used
> >for all kinds of things:
> > * Syncing with SyncML clients.
> > * Syncing with SyncML clients.
> > * The two sides in a local sync.
> > * To store username/password once for several other sync or
> >source
> > configs (see "id:<name of config with credentials>" in
the NEWS
> > file).
> But that's the thing. So we have 4 (I guess... one of the first two
> would be "server" yeah?)
Yes, a typo.
> entirely different concepts,
I wouldn't call these entirely different concepts. They all provide
information about a peer, so "peer config" looks like suitable generic
term.
As said in the other mail, that does not rule out using more specific
terms where applicable ("a target config is a special peer config").
> >I'm fine with introducing a separate term for this, but it needs to be
> >something that fits. My own best idea was and still is "per-peer store
> >properties".
> I'm fine with that. Are these used for anything but a sync though?
No, not at the moment. I just don't find "sync config" suitable due to
the legacy usage of that term.
--
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.
6:39 p.m.
------ Original Message ------
From: "Patrick Ohly" <patrick.ohly(a)intel.com>
To: "Emiliano Heyns" <emiliano.heyns(a)iris-advies.com>
Cc: "Todd Wilson" <twilson(a)csufresno.edu>; "Graham Cobb"
<g+syncevolution(a)cobb.uk.net>; "SyncEvolution"
<syncevolution(a)syncevolution.org>; "Ove Kåven" <ovek(a)arcticnet.no>
Sent: 17-4-2014 16:42:37
Subject: Re: documentation update, enhanced command line
On Thu, 2014-04-17 at 09:58 +0000, Emiliano Heyns wrote:
> On 17/04/2014 11:01:24, "Patrick Ohly" <patrick.ohly(a)intel.com>
>wrote:
>
> > I am entirely open to ditching client endpoints. I feel iffy about
> >'sync
> >> config' because it is so generic; it doesn't really disclose
>anything
> >> except 'it does something with sync' -- but then, everything of
> >> syncevolution does something with sync.
> >
> >"sync config" has to be fairly generic, because sync configs are
>used
> >for all kinds of things:
> > * Syncing with SyncML clients.
> > * Syncing with SyncML clients.
> > * The two sides in a local sync.
> > * To store username/password once for several other sync or
> >source
> > configs (see "id:<name of config with credentials>" in the
NEWS
> > file).
> But that's the thing. So we have 4 (I guess... one of the first two
> would be "server" yeah?)
Yes, a typo.
> entirely different concepts,
I wouldn't call these entirely different concepts. They all provide
information about a peer, so "peer config" looks like suitable generic
term.
I disagree, I really do. For starters, number 4 doesn't describe a peer,
it just holds referencable properties. A peer might use these, but also
a store, and there's nothing number 4 is paired with where they're
conceptual equals; instead, there is a very strict use-relation between
the bag-of-properties and the user-of-the-bag-of-properties. I am not a
peer with the knives in my kitchen.
The first two might both describe a peer, but these are very different
kind of peers; "nginx" and "chrome" are peers in a web-browsing
session,
but if you'd have to describe a HTTP exchange in terms of "the peer
sends a HTTP GET request to the other peer, who responds by sending back
a success or fault response code to the first peer", this would not be
meaningful to someone who doesn't already know that "the peer" is a
server-peer, and "the other peer" is a client-peer, and that switching
them around would simply not work; the wording implies a same-ness that
simply isn't there. They are only peers in the sense that they are
paired, but they're in no sense equals, or "something that is, at a
level equal (to that of something else)".
As said in the other mail, that does not rule out using more specific
terms where applicable ("a target config is a special peer config").
But
is there a scenario where the 'peers' in a sync are indeed 'at a
level equal'? Perhaps the "two sides in a local sync"; I'd have to go
find out what a "local sync" means other than "a client-server sync with
the network bits short-cut".
> >I'm fine with introducing a separate term for this, but
it needs to
>be
> >something that fits. My own best idea was and still is "per-peer
>store
> >properties".
> I'm fine with that. Are these used for anything but a sync though?
No, not at the moment. I just don't find "sync config" suitable due to
the legacy usage of that term.
That I understand, and I do not contest. Re-use for a different meaning
would only make matters worse.
Regards,
Emile
7:37 p.m.
On Thu, 2014-04-17 at 18:39 +0000, Heyns Emiliano wrote:
------ Original Message ------
From: "Patrick Ohly" <patrick.ohly(a)intel.com>
To: "Emiliano Heyns" <emiliano.heyns(a)iris-advies.com>
Cc: "Todd Wilson" <twilson(a)csufresno.edu>; "Graham Cobb"
<g+syncevolution(a)cobb.uk.net>; "SyncEvolution"
<syncevolution(a)syncevolution.org>; "Ove Kåven" <ovek(a)arcticnet.no>
Sent: 17-4-2014 16:42:37
Subject: Re: documentation update, enhanced command line
>On Thu, 2014-04-17 at 09:58 +0000, Emiliano Heyns wrote:
>> On 17/04/2014 11:01:24, "Patrick Ohly" <patrick.ohly(a)intel.com>
>>wrote:
>>
>> > I am entirely open to ditching client endpoints. I feel iffy about
>> >'sync
>> >> config' because it is so generic; it doesn't really disclose
>>anything
>> >> except 'it does something with sync' -- but then, everything
of
>> >> syncevolution does something with sync.
>> >
>> >"sync config" has to be fairly generic, because sync configs are
>>used
>> >for all kinds of things:
>> > * Syncing with SyncML clients.
>> > * Syncing with SyncML clients.
>> > * The two sides in a local sync.
>> > * To store username/password once for several other sync or
>> >source
>> > configs (see "id:<name of config with credentials>" in the
NEWS
>> > file).
>> But that's the thing. So we have 4 (I guess... one of the first two
>> would be "server" yeah?)
>
>Yes, a typo.
>
>> entirely different concepts,
>
>I wouldn't call these entirely different concepts. They all provide
>information about a peer, so "peer config" looks like suitable generic
>term.
I disagree, I really do. For starters, number 4 doesn't describe a peer,
it just holds referencable properties.
... about a peer. For example, syncURL or remoteDeviceID must be set to
something identifying the peer, otherwise GNOME keyring can't be used.
It's not required otherwise, but the intention is the same. This is
information about how to log into a peer, the same information that is
also stored in other peer configs.
They are only peers in the sense that they are
paired, but they're in no sense equals, or "something that is, at a
level equal (to that of something else)".
So your concern is that "peer" implies "equals". I chose that term
intentionally because I wanted to have a word that includes both client
and server. Instead of saying "the client or server that SyncEvolution
talks to" I wanted to say just "the peer that SyncEvolution talks to".
This is relevant for the part of SyncEvolution that needs to be generic.
>As said in the other mail, that does not rule out using more
specific
>terms where applicable ("a target config is a special peer config").
But is there a scenario where the 'peers' in a sync are indeed 'at a
level equal'?
That's not the point. In a particular application of the generic
concepts in SyncEvolution (for example, in a HOWTO) it makes sense to
use more specific terms. In the README.rst where the command line
options for setting up a "peer config" are described it doesn't.
--
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.
8:05 p.m.
------ Original Message ------
From: "Patrick Ohly" <patrick.ohly(a)intel.com>
To: "Heyns Emiliano" <emiliano.heyns(a)iris-advies.com>
Cc: "Todd Wilson" <twilson(a)csufresno.edu>; "Graham Cobb"
<g+syncevolution(a)cobb.uk.net>; "SyncEvolution"
<syncevolution(a)syncevolution.org>; "Ove Kåven" <ovek(a)arcticnet.no>
Sent: 18-4-2014 21:37:50
Subject: Re: Re[2]: documentation update, enhanced command line
> I disagree, I really do. For starters, number 4 doesn't describe a
>peer,
> it just holds referencable properties.
... about a peer.
Which makes it "not a peer". I am not my drivers'
license.
> They are only peers in the sense that they are
> paired, but they're in no sense equals, or "something that is, at a
> level equal (to that of something else)".
So your concern is that "peer" implies "equals".
"peer" doesn't imply equals, it means equals; from wiktionary, for
example: "something that is, at a level equal (to that of something
else)".
I chose that term
intentionally because I wanted to have a word that includes both client
and server. Instead of saying "the client or server that SyncEvolution
talks to" I wanted to say just "the peer that SyncEvolution talks to".
This is relevant for the part of SyncEvolution that needs to be
generic.
So the word peer is then entirely appropriate there. If there is indeed
a place where you want to say "client or server, doesn't matter which",
then for the scope of that discussion, these are indeed equals. But
anywhere where you want to talk about clients or servers, even if they
figure as true peers elsewhere, these are not peers. There are parts
where the explanation of what SyncEvolution does and how it does it is
appropriately non-generic.
> >As said in the other mail, that does not rule out using more
>specific
> >terms where applicable ("a target config is a special peer config").
> But is there a scenario where the 'peers' in a sync are indeed 'at a
> level equal'?
That's not the point. In a particular application of the generic
concepts in SyncEvolution (for example, in a HOWTO) it makes sense to
use more specific terms. In the README.rst where the command line
options for setting up a "peer config" are described it doesn't.
Fine,
I'll accede that point. That describes a general mechanism for
setting up "things that figure in a paired set that are to be synched"
(and for the scope of that description, they are equals), for which the
configuration commands happen to be alike. But at some point anyone who
wants to use SyncEvolution will want to set up specific kinds of things
that happen to be configurable by setting up a peer config in a specific
way. I haven't seen any example so far that sets up a peer for actual
use that doesn't have a very specific role (and the ones I've found so
far are 'client', 'server' and perhaps that 'bag of properties ready
for
use' kind), and knowing and being able to name this purpose is very
important for making understandable documentation.
I don't think this debate is leading us somewhere fruitful, however.
I'll keep with the 'peer' terminology, which I think is already a step
above 'sync config'. I think the use of the term peer for something like
candidate #4 (the bag of referencable properties) where that does not
represent an actant is a category mistake, but I'm not going to push
that point any further, and focus on getting something out that is
useful for the starting user, uses terminology from the updated
README.rst you mailed where possible, and will nowhere contradict it.
Regards,
Emile
8:37 p.m.
I don't think we have consensus on the revised terminology. My updated
readme will need further changes.
At this point I'd like to get feedback from others before proceeding.
Graham, Ove, Todd?
It's now Eastern, and I'll be away for a few days myself. Let's not hurry.
Bye, Patrick
Am 18.04.2014 22:06 schrieb "Heyns Emiliano" <emiliano.heyns(a)iris-advies.com
:
------ Original Message ------
From: "Patrick Ohly" <patrick.ohly(a)intel.com>
To: "Heyns Emiliano" <emiliano.heyns(a)iris-advies.com>
Cc: "Todd Wilson" <twilson(a)csufresno.edu>; "Graham Cobb" <
g+syncevolution(a)cobb.uk.net>; "SyncEvolution" <
syncevolution(a)syncevolution.org>; "Ove Kåven" <ovek(a)arcticnet.no>
Sent: 18-4-2014 21:37:50
Subject: Re: Re[2]: documentation update, enhanced command line
> I disagree, I really do. For starters, number 4 doesn't describe a peer,
>> it just holds referencable properties.
>>
>
> ... about a peer.
>
Which makes it "not a peer". I am not my drivers' license.
>
> They are only peers in the sense that they are
>> paired, but they're in no sense equals, or "something that is, at a
>> level equal (to that of something else)".
>>
>
> So your concern is that "peer" implies "equals".
>
"peer" doesn't imply equals, it means equals; from wiktionary, for
example: "something that is, at a level equal (to that of something else)".
I chose that term
> intentionally because I wanted to have a word that includes both client
> and server. Instead of saying "the client or server that SyncEvolution
> talks to" I wanted to say just "the peer that SyncEvolution talks
to".
> This is relevant for the part of SyncEvolution that needs to be generic.
>
So the word peer is then entirely appropriate there. If there is indeed a
place where you want to say "client or server, doesn't matter which", then
for the scope of that discussion, these are indeed equals. But anywhere
where you want to talk about clients or servers, even if they figure as
true peers elsewhere, these are not peers. There are parts where the
explanation of what SyncEvolution does and how it does it is appropriately
non-generic.
>
>
> >As said in the other mail, that does not rule out using more specific
>> >terms where applicable ("a target config is a special peer
config").
>> But is there a scenario where the 'peers' in a sync are indeed 'at
a
>> level equal'?
>>
>
> That's not the point. In a particular application of the generic
> concepts in SyncEvolution (for example, in a HOWTO) it makes sense to
> use more specific terms. In the README.rst where the command line
> options for setting up a "peer config" are described it doesn't.
>
Fine, I'll accede that point. That describes a general mechanism for
setting up "things that figure in a paired set that are to be synched" (and
for the scope of that description, they are equals), for which the
configuration commands happen to be alike. But at some point anyone who
wants to use SyncEvolution will want to set up specific kinds of things
that happen to be configurable by setting up a peer config in a specific
way. I haven't seen any example so far that sets up a peer for actual use
that doesn't have a very specific role (and the ones I've found so far are
'client', 'server' and perhaps that 'bag of properties ready for
use'
kind), and knowing and being able to name this purpose is very important
for making understandable documentation.
I don't think this debate is leading us somewhere fruitful, however. I'll
keep with the 'peer' terminology, which I think is already a step above
'sync config'. I think the use of the term peer for something like
candidate #4 (the bag of referencable properties) where that does not
represent an actant is a category mistake, but I'm not going to push that
point any further, and focus on getting something out that is useful for
the starting user, uses terminology from the updated README.rst you mailed
where possible, and will nowhere contradict it.
Regards,
Emile
9:51 p.m.
On Fri, Apr 18, 2014 at 10:37 PM, Ohly, Patrick <patrick.ohly(a)intel.com>wrote:
I don't think we have consensus on the revised terminology. My
updated
readme will need further changes.
I understand that it will; I'll keep tracking those changes. I feel I sort
of
have a grasp on things now, and I want to start writing while it's fresh
in my mind. If the conceptual model that I have in my head is wrong, it'll
need revising anyhow. If the model is OK but the terminology is off, that
should be easy enough to fix. I find it easier in general to have something
flawed out for correction than to try and aim for perfection before
starting; it's easier to point out flaws than to built something without
flaws. I don't mind rework.
At this point I'd like to get feedback from others before
proceeding.
Graham, Ove, Todd?
That is OK.
It's now Easter, and I'll be away for a few days myself.
Let's not hurry.
Alright, have a fun few days off. I don't have any plans for easter except
essay writing, so I'm going to have a stab at the doc. Nothing irreversible
(or af any impact, really) can be done by me, so I don't see any dangers
except me perhaps wasting a few hours, and I don't mind that.
Am 18.04.2014 22:06 schrieb "Heyns Emiliano" <
emiliano.heyns(a)iris-advies.com>:
You're German? I hadn't figured that from your English.
Regards,
Emile
6:36 a.m.
On Fri, 2014-04-18 at 23:51 +0200, Emiliano Heyns wrote:
On Fri, Apr 18, 2014 at 10:37 PM, Ohly, Patrick
<patrick.ohly(a)intel.com> wrote:
I don't think we have consensus on the revised terminology. My
updated readme will need further changes.
I understand that it will; I'll keep tracking those changes. I feel I
sort of have a grasp on things now, and I want to start writing while
it's fresh in my mind. If the conceptual model that I have in my head
is wrong, it'll need revising anyhow. If the model is OK but the
terminology is off, that should be easy enough to fix. I find it
easier in general to have something flawed out for correction than to
try and aim for perfection before starting; it's easier to point out
flaws than to built something without flaws. I don't mind rework.
Okay. I was just worried that you might get disappointed when the
terminology changes again.
You're German? I hadn't figured that from your English.
You should hear me talk... ;-}
--
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.
11:10 a.m.
On Wed, Apr 23, 2014 at 8:36 AM, Patrick Ohly <patrick.ohly(a)intel.com>wrote:
On Fri, 2014-04-18 at 23:51 +0200, Emiliano Heyns wrote:
> On Fri, Apr 18, 2014 at 10:37 PM, Ohly, Patrick
> <patrick.ohly(a)intel.com> wrote:
> I don't think we have consensus on the revised terminology. My
> updated readme will need further changes.
>
> I understand that it will; I'll keep tracking those changes. I feel I
> sort of have a grasp on things now, and I want to start writing while
> it's fresh in my mind. If the conceptual model that I have in my head
> is wrong, it'll need revising anyhow. If the model is OK but the
> terminology is off, that should be easy enough to fix. I find it
> easier in general to have something flawed out for correction than to
> try and aim for perfection before starting; it's easier to point out
> flaws than to built something without flaws. I don't mind rework.
Okay. I was just worried that you might get disappointed when the
terminology changes again.
I'm a scrum master at work; I tend to prefer flawed products over perfect
concepts. I've pushed out a new version at
http://reichenhack.github.io/syncevolution.html that now adds google sync;
I'd love it if someone could go over it to see if there are mistakes left.
I know there are many commands that con be combined; I intend to add that
as a separate section as soon as I know the verbose explanation is correct.
If that turns out to be the case, then these are the next steps:
1. OAuth2 for Google
2. Compact command lines, setting up multiple configs in one go
3. Start rewriting the other HOWTO's I find strewn about building off this
one.
Regards,
Emile
2:19 p.m.
On Wed, 2014-04-23 at 13:10 +0200, Emiliano Heyns wrote:
I've pushed out a new version at
http://reichenhack.github.io/syncevolution.html that now adds google
sync; I'd love it if someone could go over it to see if there are
mistakes left.
| syncevolution --configure --template none backend=file
| database="file:///tmp/my-contacts-store" databaseformat=text/vcard
| @local local-contacts
| I did not explicitly create the datastore or the contexts; both are
| created when first referenced, and updated if they already exist. I
| also did not explicitly tell SyncEvolution that we're setting up a
| datastore (rather than a sync-config, which we'll set up with a
| similar command); SyncEvolution knows that we're configuring a
| datastore because we are passing it properties that are relevant to
| datastores.
This is not quite correct. SyncEvolution does not look at the properties
to determine what is meant to be changed. That is determined exclusively
by the sync config and source names (@local and local-contacts in the
example above). The configs corresponding to that will get updated with
the properties from the command line that match the entity that gets
updated (sync properties go into the sync config, source properties into
the source configs, foo/<source property> goes into the config of source
foo).
I've only briefly scanned the rest of the document; looks good.
--
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.
2:20 p.m.
Super, thanks. I'll update the document over the weekend.
On Thu, May 22, 2014 at 4:19 PM, Patrick Ohly <patrick.ohly(a)intel.com>wrote:
On Wed, 2014-04-23 at 13:10 +0200, Emiliano Heyns wrote:
> I've pushed out a new version at
> http://reichenhack.github.io/syncevolution.html that now adds google
> sync; I'd love it if someone could go over it to see if there are
> mistakes left.
| syncevolution --configure --template none backend=file
| database="file:///tmp/my-contacts-store" databaseformat=text/vcard
| @local local-contacts
| I did not explicitly create the datastore or the contexts; both are
| created when first referenced, and updated if they already exist. I
| also did not explicitly tell SyncEvolution that we're setting up a
| datastore (rather than a sync-config, which we'll set up with a
| similar command); SyncEvolution knows that we're configuring a
| datastore because we are passing it properties that are relevant to
| datastores.
This is not quite correct. SyncEvolution does not look at the properties
to determine what is meant to be changed. That is determined exclusively
by the sync config and source names (@local and local-contacts in the
example above). The configs corresponding to that will get updated with
the properties from the command line that match the entity that gets
updated (sync properties go into the sync config, source properties into
the source configs, foo/<source property> goes into the config of source
foo).
I've only briefly scanned the rest of the document; looks good.
--
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.
12:48 p.m.
On 17/04/2014 11:01:24, "Patrick Ohly" <patrick.ohly(a)intel.com> wrote:
"sync config" has to be fairly generic, because sync configs are used
for all kinds of things:
* Syncing with SyncML clients.
* Syncing with SyncML clients.
* The two sides in a local sync.
* To store username/password once for several other sync or
source
configs (see "id:<name of config with credentials>" in the NEWS
file).
For sake of clarity: I am fine with keeping the generic name 'sync
config', as a generic name for:
1. Can hold the configuration of a SE SyncML Server
2. Can hold the configuration of a SE SyncML Client
3. ....
I need these concepts for my documentation, because these are important
concepts in understanding what SE can do, and how it does it. That would
still mean that 'setting up an SE SyncML client by assembling a
particular sync config' would have a meaningful concept of 'an SE SyncML
client'. It is these that I am looking for.
Regards,
Emile
8:32 p.m.
------ Original Message ------
From: "Patrick Ohly" <patrick.ohly(a)intel.com>
To: "Emiliano Heyns" <emiliano.heyns(a)iris-advies.com>
Cc: "Todd Wilson" <twilson(a)csufresno.edu>; "Graham Cobb"
<g+syncevolution(a)cobb.uk.net>; "SyncEvolution"
<syncevolution(a)syncevolution.org>; "Ove Kåven" <ovek(a)arcticnet.no>
Sent: 16-4-2014 22:05:27
Subject: Re: documentation update, enhanced command line
The next phase then would be to pick the exact wording for
README.rst,
using these agreed terms. We should do this using git commits in actual
repos, to facilitate merging and change tracking. If someone wants to
propose new text for the README.rst, please clone the new "doc" branch
in http://cgit.freedesktop.org/SyncEvolution/syncevolution/?h=doc and
post patches in "git format-patch" style to the list. Optionally also
push the updated git tree somewhere (github?), in particular if it
involves merges.
Does freedesktop.org allow for something like github's pull
requests?
Wouldn't that be easier (and less clutter for the list-readers)?
Regards,
Emile
9:18 p.m.
Another suggestion I would like to make is that it can also make sense to
split up the manpage into more than one. For example, there could be a
syncevolution_config (5) manpage that lists and gives explanations of all
the configuration properties, so that the syncevolution (1) manpage could
just focus on the command-line switches. The man pages of many other
programs with substantial configuration files are organized that way (ssh,
sshd, openssl, dhclient, ntp, smb, and others come to mind).
--Todd
Todd Wilson, PhD
Department of Computer Science
California State University, Fresno
On Wed, Apr 16, 2014 at 1:05 PM, Patrick Ohly <patrick.ohly(a)intel.com>wrote:
On Wed, 2014-04-16 at 19:43 +0200, Emiliano Heyns wrote:
> More specifically, I think we need to converge, not diverge the
> terminology. I *have* diverted from the existing syncevolution
> terminology where I think they suggest commonality where there is
> none; perhaps the technical implementation of the configuration of
> target-config and sync config share code, but if my understanding of
> them is correct, their behavior is non-trivially different, and that I
> have reflected in new naming.
>
> I am in no way specifically enamored by the new names I introduced,
> and I'll gladly swap them for others, but to have 3 sets of terms in
> play is not going to be helpful I think.
I agree, we need to agree on updated terminology and (where necessary)
functional changes before we can adapt HOWTOs. The problem with the
HOWTOs is (and always has been) that many users will be on SyncEvolution
1.4 or even older for a while to come.
Any new HOWTO depending on new functionality will have to be very
explicit about the version of SyncEvolution that it depends on, and we
cannot remove the "old" content that it replaces right away.
Regarding converging: we can follow two approaches or perhaps phases.
First we reach consensus on key terms. Contentious (or at least not
explicitly accepted) are:
* "originating source" in a local sync (proposed by me).
* "source" vs. "store" (I think both Todd and Emile preferred
store).
* "Client Endpoints" instead of "sync configs" (Emile)
* "Synced stores" as new term for the per-peer source properties
(Emile)
The next phase then would be to pick the exact wording for README.rst,
using these agreed terms. We should do this using git commits in actual
repos, to facilitate merging and change tracking. If someone wants to
propose new text for the README.rst, please clone the new "doc" branch
in http://cgit.freedesktop.org/SyncEvolution/syncevolution/?h=doc and
post patches in "git format-patch" style to the list. Optionally also
push the updated git tree somewhere (github?), in particular if it
involves merges.
I've push my own proposal there, but it is not final because I think I
will pick up more of your proposals once their is consensus on terms.
Regarding the new terms, here's my position:
+1 for "originating source". I think it is needed.
+1 for "store" instead of "source". I agree with Todd's
explanation that
the source incorrectly implies a data direction.
-1 for "Client Endpoints". This is misleading because the same thing is
also needed for servers. "sync config" covers both because it is
neutral.
-1 "Synced stores". This just doesn't sound right to me, but I cannot
quite nail why. Perhaps because I simply don't think of this as real
entities, just as some additional settings for a source (or soon,
store).
--
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.
8:53 a.m.
On Wed, 2014-04-16 at 14:18 -0700, Todd Wilson wrote:
Another suggestion I would like to make is that it can also make
sense
to split up the manpage into more than one. For example, there could
be a syncevolution_config (5) manpage that lists and gives
explanations of all the configuration properties, so that the
syncevolution (1) manpage could just focus on the command-line
switches. The man pages of many other programs with substantial
configuration files are organized that way (ssh, sshd, openssl,
dhclient, ntp, smb, and others come to mind).
So you would split out the "CONFIGURATION PROPERTIES" section with the
automatically generated config property descriptions? What about the
description of the term "property"? If we move that into
syncevolution_config, the syncevolution man page itself may become less
comprehensible.
--
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.
2:33 p.m.
How does this git repo relate to the one at
https://github.com/shadeslayer/Syncevolution? Using github would make it
easier to keep repositories in sync (I think)
On Apr 16, 2014 10:05 PM, "Patrick Ohly" <patrick.ohly(a)intel.com> wrote:
On Wed, 2014-04-16 at 19:43 +0200, Emiliano Heyns wrote:
> More specifically, I think we need to converge, not diverge the
> terminology. I *have* diverted from the existing syncevolution
> terminology where I think they suggest commonality where there is
> none; perhaps the technical implementation of the configuration of
> target-config and sync config share code, but if my understanding of
> them is correct, their behavior is non-trivially different, and that I
> have reflected in new naming.
>
> I am in no way specifically enamored by the new names I introduced,
> and I'll gladly swap them for others, but to have 3 sets of terms in
> play is not going to be helpful I think.
I agree, we need to agree on updated terminology and (where necessary)
functional changes before we can adapt HOWTOs. The problem with the
HOWTOs is (and always has been) that many users will be on SyncEvolution
1.4 or even older for a while to come.
Any new HOWTO depending on new functionality will have to be very
explicit about the version of SyncEvolution that it depends on, and we
cannot remove the "old" content that it replaces right away.
Regarding converging: we can follow two approaches or perhaps phases.
First we reach consensus on key terms. Contentious (or at least not
explicitly accepted) are:
* "originating source" in a local sync (proposed by me).
* "source" vs. "store" (I think both Todd and Emile preferred
store).
* "Client Endpoints" instead of "sync configs" (Emile)
* "Synced stores" as new term for the per-peer source properties
(Emile)
The next phase then would be to pick the exact wording for README.rst,
using these agreed terms. We should do this using git commits in actual
repos, to facilitate merging and change tracking. If someone wants to
propose new text for the README.rst, please clone the new "doc" branch
in http://cgit.freedesktop.org/SyncEvolution/syncevolution/?h=doc and
post patches in "git format-patch" style to the list. Optionally also
push the updated git tree somewhere (github?), in particular if it
involves merges.
I've push my own proposal there, but it is not final because I think I
will pick up more of your proposals once their is consensus on terms.
Regarding the new terms, here's my position:
+1 for "originating source". I think it is needed.
+1 for "store" instead of "source". I agree with Todd's
explanation that
the source incorrectly implies a data direction.
-1 for "Client Endpoints". This is misleading because the same thing is
also needed for servers. "sync config" covers both because it is
neutral.
-1 "Synced stores". This just doesn't sound right to me, but I cannot
quite nail why. Perhaps because I simply don't think of this as real
entities, just as some additional settings for a source (or soon,
store).
--
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.
11:02 a.m.
New subject: [SyncEvolution] documentation update, enhanced command line - second attempt
Hello!
Let's revive this mail thread once more. The goal is to agree on a
change of the README.rst, in particular in the terminology section, and
then make the necessary code changes to match that change.
I don't want to make code changes unless other developers or users agree
that the changes are an improvement, so please provide feedback.
This work is in the "doc" branch of the git repo
(http://cgit.freedesktop.org/SyncEvolution/syncevolution). When you want
to propose changes, please do so as patches against the repo. The branch
can be tracked, I am not going to rebase it until we are done.
Attached is a diff against the current master.
As a reminder, we agreed on some aspects:
* Better explain what local sync is and how it involves two sync
configs. "originating config" gets introduces instead of just
"sync config".
* "data source" -> "datastore"
* 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.
I also already fixed some mistakes:
* 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.
I had also proposed to revise some of the magic that --configure does
when setting up a new config. I'm backing off of that and want to keep
the behavior as it is at the moment, because I am not sure how some
things should work without that magic.
Here's the list of changes made since I first proposed the revised
README.rst:
commit c4fb7a1d1843a13cbc1b78a62c3c977a76fede7d
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Fri May 23 12:54:14 2014 +0200
README.rst: data source -> datastore
The word "source" implies reading, while in fact it is read/write.
"datastore" avoids that misconception.
"data store" in two words could also have been used; not sure which
spelling is better.
While renaming, also remove references to explicit --*-property
parameters. The only necessary use today is "--sync-property ?"
and "--datastore-property ?".
--source-property must remain valid for backward compatility.
--datastore-property was used instead of the short --store-property
because "store" might be mistaken for the verb. It doesn't matter
that it is longer because it doesn't get typed often.
commit a00a7468e6de0379a4347b72346a5267c7258d0f
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Fri May 23 12:05:20 2014 +0200
README.rst: lanugage tweaks
Be more clear about the local side of a sync.
Avoid "access a peer" when talking about a sync config, because
"access" implies that sync is initiated using the sync config, which
is not the case for SyncML server sync configs in a client-initiated
sync. "talk with peer" is more neutral.
commit c3299e1685880cdc31e24e0a5586d90c549cdecb
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Fri May 23 11:59:27 2014 +0200
README.rst: remove TODO remarks
syncevo-webdav-lookup works again in master. Keep the current
--configure behavior for now.
commit 28a99276e42fd3b505ab17af25ec26c68ca3c813
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Fri May 23 11:56:10 2014 +0200
README.rst: add "item" term
Todd Wilson correctly pointed out that it was missing.
--
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.
3:05 p.m.
New subject: [SyncEvolution] documentation update, enhanced command line - second attempt
On Fri, 2014-05-23 at 13:02 +0200, Patrick Ohly wrote:
Let's revive this mail thread once more. The goal is to agree on
a
change of the README.rst, in particular in the terminology section, and
then make the necessary code changes to match that change.
I don't want to make code changes unless other developers or users agree
that the changes are an improvement, so please provide feedback.
There hasn't been much feedback on this particular proposal. Looks like
I need to make a judgment call myself.
I think we identified some useful improvements, so I went ahead with the
proposal. The updated "doc" branch addresses the TODOs identified in the
proposal and should be ready for merging into the master branch.
My plan is to run a full test run over the weekend and give some time
for feedback, say until the middle of next week. Then I could release a
1.4.99.4 snapshot either before or after a two week vacation - perhaps
better after it, in case the update breaks anything.
Attached is the resulting README.html file. Note in particular that this
finally addresses the current situation with Google syncing (SyncML
turned off, CardDAV/CalDAV better done with OAuth) by introducing a
single Google template that works for CardDAV and CalDAV in a single
context.
Changes since the last update:
commit 57f44fe607292d624135d11f96eb1c3cefa093b6
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Wed Jul 23 20:21:14 2014 +0200
config: allow storing credentials for email address
When configuring a WebDAV server with username = email address and no
URL (which is possible if the server supports service discovery via
the domain in the email address), then storing the credentials in the
GNOME keyring used to fail with "cannot store password in GNOME
keyring, not enough attributes".
That is because GNOME keyring seemed to get confused when a network
login has no server name and some extra safeguards were added to
SyncEvolution to avoid this.
To store the credentials in the case above, the email address now gets
split into user and domain part and together get used to look up the
password.
commit 5ab328af07a746c5bf881b05e5d4a4bd546fc36d
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Thu Jul 24 10:51:13 2014 +0200
D-Bus testing: fix race condition in TestLocalSync.testNoParent
The first progress signal gets emitted after sleeping for 10 seconds
at the start of the sync and then killing syncevo-dbus-server races
with completing the sync. What we want is to kill during the 10 second
wait, so we better wait for the debug output directly before it and
then kill directly.
commit 8c6f770e386f63b6b2d83edca374c20e75e59ec9
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Wed Jul 23 21:12:25 2014 +0200
local sync: allow config name in syncURL=local://
Previously, only syncURL=local://@<context name> was allowed and used
the "target-config@context name" config as target side in the local
sync.
Now "local://config-name@context-name" or simply
"local://config-name"
are also allowed. "target-config" is still the fallback if only a
context is give.
It also has one more special meaning: "--configure
target-config@google-calendar" will pick the "Google_Calendar"
template automatically because it knows that the intention is to
configure the target side of a local sync. It does not know that when
using some other name for the config, in which case the template (if
needed) must be specified explicitly.
The process name in output from the target side now also includes the
configuration name if it is not the default "target-config".
commit f14dafbd33cd8d6695c7aa791baf8ea4e1083aa9
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Fri Jul 25 11:09:12 2014 +0200
WebDAV: support multiple URLs in syncURL
The syncURL property may contain multiple different space or tab
separated URLs. Previously, the WebDAV backend only used the first one
when scanning for databases. Now it tries all of them.
This will be useful for configuring all Google endpoints in one
template.
commit df1205c141c7bc70fe6d456ec3ff92bca5f5aac5
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Fri Jul 25 14:02:29 2014 +0200
Google: remove SyncML template, combine CalDAV/CardDAV
Google has turned off their SyncML server, so the corresponding
"Google Contacts" template became useless and needs to be removed. It
gets replaced by a "Google" template which combines the three
different URLs currently used by Google for CalDAV/CardDAV.
This new template can be used to configure a "target-config@google"
with default calendar and address book database already enabled. The
actual URL of these databases will be determined during the first
sync using them.
The template relies on the WebDAV backend's new capability to search
multiple different entries in the syncURL property for databases. To
avoid listing each calendar twice (once for the legacy URL, once with
the new one) when using basic username/password authentication, the
backend needs a special case for Google and detect that the legacy URL
does not need to be checked.
commit 6bbde198c96e5717bdb19d9d1b6d0a7a5ae9fd05
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Wed Jul 23 20:27:54 2014 +0200
doc: remove TODO about username = email address
Fix pending for inclusion in master branch.
commit b24008b28001082333c7c3a7a2a7b45e829677b5
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Wed Jul 23 20:31:44 2014 +0200
doc: fix compilation, minor language fixes
reStructured text syntax was slightly broken, preventing compilation.
Also, syncevolution does not know about --datastore-properties yet.
Changed language slightly during fresh pass.
commit 5e6efbbd6b9386778e3ff1b40ecea0982d8b7b0d
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Thu Jul 24 11:13:14 2014 +0200
source -> datastore rename
"--datastore-property" is now the preferred parameter
name. "--source-property" is still supported as alias for backward
compatibility.
As many user-visible instances of "source" as possible got replaced in
text strings by the newer term "datastore". Debug messages were left
unchanged unless some regex happened to match it.
The source code will continue to use the old variable and class names
based on "source".
commit 45888df64c550638c7eb991f735ea91e2aae1fb6
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Fri Jul 25 14:43:17 2014 +0200
doc: remove TODO about preventSlowSync
This is now tracked in FDO #76471.
commit 8c2ab09f7864ac89596c53e542c1b3a3e2b7bf63
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Fri Jul 25 15:42:52 2014 +0200
doc: syncURL property help text formatting
When embedding help text in README.rst, a blank line is needed
after the verbatim code block.
commit d22335d8d6db3a3bb5792564d2feff43ea8614cb
Author: Patrick Ohly <patrick.ohly(a)intel.com>
Date: Fri Jul 25 15:44:51 2014 +0200
doc: document new Google template and OAuth via GOA
--
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.
7:58 a.m.
New subject: [SyncEvolution] documentation update, enhanced command line - second attempt
Hi Patrick,
On Fri, Jul 25, 2014 at 8:35 PM, Patrick Ohly <patrick.ohly(a)intel.com>
wrote:
On Fri, 2014-05-23 at 13:02 +0200, Patrick Ohly wrote:
> Let's revive this mail thread once more. The goal is to agree on a
> change of the README.rst, in particular in the terminology section,
> and
> then make the necessary code changes to match that change.
>
> I don't want to make code changes unless other developers or users
> agree
> that the changes are an improvement, so please provide feedback.
I did like the new terminology. Its much better than previous one. Easy
to understand. Also old terminology still works as fallback which is
good.
One thing I always struggle, is to initiate a sync between two
evolution databases defined in different contexts (without running
syncevolution http server).
For example, lets say I have two calendars on evolution; Work &
Personal. And they are defined like this (with new terminology):
syncevolution --configure --template none backend=evolution-calendar
database=Work @Local workcal
syncevolution --configure --template none backend=evolution-calendar
database=Personal @EDS personalcal
How to initiate a sync between them? Which one will act as client &
which one as server?
Is it necessary to define them in different contexts(@Local, @EDS) at
all? What if both are defined within @Local? Is it, then, possible to
initiate a sync between them?
7:36 a.m.
New subject: [SyncEvolution] documentation update, enhanced command line - second attempt
On Sun, 2014-07-27 at 08:03 +0005, Khurshid Alam wrote:
Hi Patrick,
On Fri, Jul 25, 2014 at 8:35 PM, Patrick Ohly <patrick.ohly(a)intel.com>
wrote:
> On Fri, 2014-05-23 at 13:02 +0200, Patrick Ohly wrote:
> Let's revive this mail thread once more. The goal is to
> agree on a change of the README.rst, in particular in the
> terminology section, and then make the necessary code
> changes to match that change. I don't want to make code
> changes unless other developers or users agree that the
> changes are an improvement, so please provide feedback.
I did like the new terminology. Its much better than previous one.
Easy to understand. Also old terminology still works as fallback which
is good.
Thanks for the heads up.
One thing I always struggle, is to initiate a sync between two
evolution databases defined in different contexts (without running
syncevolution http server).
You'll need the local sync feature for that.
For example, lets say I have two calendars on evolution; Work &
Personal. And they are defined like this (with new terminology):
syncevolution --configure --template none backend=evolution-calendar
database=Work @Local workcal
syncevolution --configure --template none backend=evolution-calendar
database=Personal @EDS personalcal
How to initiate a sync between them?
SyncEvolution can only sync between peers. The peers are where
SyncEvolution maintains meta data relevant for running multiple,
incremental syncs. By definition, that data is not in the databases (and
can't be, because most databases simply have no way of storing it).
So to initiate a sync of these two databases, one needs two peers (or
for each DB).
Which one will act as client & which one as server?
It doesn't matter in this case. Usually it is more efficient to use the
DB which can be accessed more quickly on the server side.
Is it necessary to define them in different contexts(@Local, @EDS)
at
all? What if both are defined within @Local? Is it, then, possible to
initiate a sync between them?
It is no longer necessary to define them in different contexts. It used
to be, but I also already came to the conclusion that this was
unnecessarily restrictive.
Coming back to the example, here's how a two-way sync of these two DBs
can be set up:
syncevolution --configure --template none sync=two-way target-config@EDS personalcal
syncevolution --configure --template SyncEvolution_Client syncURL=local://@EDS
sync=two-way uri=personalcal calendars@Local workcal
syncevolution --sync slow calendars
syncevolution calendars # incremental sync
--
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.
2:33 p.m.
New subject: [SyncEvolution] documentation update, enhanced command line - second attempt
Hi,
> Which one will act as client & which one as server?
It doesn't matter in this case. Usually it is more efficient to use
the
DB which can be accessed more quickly on the server side.
What I meant was that which one would be "remote" & which one would be
"local". If one calendar is read-only I may want to perform a one-way
sync(--sync one-way-from-remote). Technically, whichever context is
used with "taget-config", is treated as "remote" in syncevolution. Is
that same here?
Coming back to the example, here's how a two-way sync of these
two DBs
can be set up:
syncevolution --configure --template none sync=two-way
target-config@EDS personalcal
syncevolution --configure --template SyncEvolution_Client
syncURL=local://@EDS sync=two-way uri=personalcal calendars@Local
workcal
syncevolution --sync slow calendars
syncevolution calendars # incremental sync
Thanks. That Worked.
2:41 p.m.
New subject: [SyncEvolution] documentation update, enhanced command line - second attempt
On Tue, 2014-07-29 at 14:38 +0005, Khurshid Alam wrote:
Hi,
> Which one will act as client & which one as server?
> It doesn't matter in this case. Usually it is more efficient to use
> the DB which can be accessed more quickly on the server side.
What I meant was that which one would be "remote" & which one would be
"local".
Your choice. It doesn't matter here, because both sides are equally "far
away" (or near).
If one calendar is read-only I may want to perform a one-way
sync(--sync one-way-from-remote). Technically, whichever context is
used with "taget-config", is treated as "remote" in syncevolution.
Is
that same here?
Yes.
"remote" is just a matter of perspective here. It means "not the side
used for starting the sync" more than it means "expensive to access" or
"on a different machine".
"remote" and "local" have nothing to do with the direction of the
data
transfer.
--
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.
2555
days inactive
2660
days old
syncevolution@synevolution.org
34 comments
6 participants
participants (6)
-
Emiliano Heyns -
Heyns Emiliano
-
Khurshid Alam -
Ohly, Patrick -
Patrick Ohly
-
Todd Wilson