Editing the Whitepaper
|
View:
New views
2 Messages
—
Rating Filter:
Alert me
|
 |
Editing the Whitepaper
by John Ladan-2
::
Rate this Message:
Hi,
This is my first contribution. While reading the white paper, I noticed a bunch of grammar errors (number, tense, syntax, etc.), so I decided to start fixing them. A few stylistic changes worked their way in to make the language a little more formal. I've only looked at the abstract and introduction so far. Let me know how you like the changes. I can keep working on it if you want. The patch for trunk is attached. -John Ladan [correct_grammar.diff] Index: docs/whitepaper/introduction.tex =================================================================== --- docs/whitepaper/introduction.tex (revision 5613) +++ docs/whitepaper/introduction.tex (working copy) @@ -6,18 +6,18 @@ \section{History} MultiSync, started by Bo Lincoln, was intended to synchronize various mobiles, PDAs and PIM applications. MultiSync was a GTK application and provided -support for different PIM applications and devices by providing plugins. -Primary focus of MultiSync was to synchronize just PIM data (contacts, +support for different PIM applications and devices by providing plugins. +The primary focus of MultiSync was to synchronize just PIM data (contacts, appointments, notes). Unfortunately this approach was fixed to a single UI and -only limited to PIM synchronization. Development branch MultiSync 0.9x was +limited to PIM synchronization. Development branch MultiSync 0.9x was intended fix those needs.\\ \\ Early in 2005, Armin Bauer started refactoring the MultiSync project and separated the UI code from MultiSync and the Plugin interface and -Synchronization logic. Result of his work is the most powerful and +Synchronization logic. The result of his work is the most powerful and flexible Synchronization Framework, known today as OpenSync. \section{Big Picture} -OpenSync is intended to provide a low-level synchronization API for all kind of +OpenSync is intended to provide a low-level synchronization API for all kinds of data. \\ \begin{figure} @@ -33,38 +33,38 @@ The goals of the OpenSync project are: \begin{itemize} - \item Reusabilty. OpenSync should be usable for all kind of synchronization + \item Reusabilty. OpenSync should be usable for all kinds of synchronization applications - \item Speed. Synchronization should be efficent and fast as possible to give the + \item Speed. Synchronization should be efficent and as fast as possible to give the user the best experience. - \item Flexibility. Nobody can predict what comes next to synchronize; after the - G- \& iPhone. So OpenSync has to be designed and built as flexible and modular + \item Flexibility. Nobody can predict what will come next to synchronize after the + G- \& iPhone, so OpenSync has to be designed and built as flexible and modular as possible. \item Integrity. Data MUST never be lost or malformed, no matter what happens. Data loss is just a no go! - \item Portability. OpenSync should just run on as many platforms as possible as + \item Portability. OpenSync should run on as many platforms as possible as possible. \item Fun. The experience of using and developing OpenSync MUST be fun! You should not work on OpenSync if you're unhappy :) \end{itemize} -Not all of the mentioned goals are reached already, but OpenSync tries to get +Not all of the mentioned goals are achieved yet, but OpenSync tries to get close as possible over time. \section{Who should read this document?} This Document is intended for everyone who is interested in a Open Source -Synchronization solution. This is not a HowTo, Tutorial or Guide how to use -OpenSync. It's a detailed introducation in the OpenSync framework. No (high) +Synchronization solution. This is not a HowTo, Tutorial or Guide on how to use +OpenSync. It is a detailed introduction of the OpenSync framework. No (high) programming skills/experince are required for this document. \section{How should this document be read?} Some chapter are very detailed about internal technial stuff, which is mainly -intended for developers or people who are interested in how OpenSync ticks. Those -chapters could be safetly skipped if someone isn't interested in touching the -internals of the OpenSync Framework. Such section are marked with a little hint. +intended for developers or people who are interested in how OpenSync works. Those +chapters could be safely skipped if someone isn't interested in touching the +internals of the OpenSync Framework. Such sections are marked with a little hint. \section{Is this the most recent version of this paper?} Maybe not, OpenSync is in a very early stage of development and lots of stuff -might changed within the last weeks. On doubts you might compare your version +might changed within the last weeks. If in doubt, you might compare your version with the one from:\\ \\ \hyperref[http://www.opensync.org/download/LATEST-WHITEPAPER]{http://www.opensync.org/download/LATEST-WHITEPAPER}\\ Index: docs/whitepaper/synchronization.tex =================================================================== --- docs/whitepaper/synchronization.tex (revision 5613) +++ docs/whitepaper/synchronization.tex (working copy) @@ -1,8 +1,8 @@ \chapter{Synchronization} -This chapter give a brief introduction of synchronization basics as well as how +This chapter gives brief introduction of synchronization basics as well as how OpenSync works and handles real life synchronization issues.\\ \\ -Different synchronization techniques used nowadays, which have some of the +Different synchronization techniques are used nowadays, which have some of the following tasks in common: \begin{itemize} \item Connect @@ -12,136 +12,148 @@ \item Commit changes \item Disconnect \end{itemize} -Those tasks are in common for synchronization technique/protocol, but differ in -detail to fit the needs for different circumstances to meet the best efficiency. -Such circumstances could be: +Those tasks are common for synchronization technique/protocol, but differ in +detail, in order to fit the needs for different circumstances and to meet the +best efficiency. Such circumstances could be: \begin{itemize} - \item Number of synchronization parties. If the number of synchronization + \item Number of synchronization parties. If number of synchronization parties is two, then multiplying of changes is just simple duplication of the change. - \item Unidirectional/Bidirectional synchronization. On unidirectional - synchronization no conflict resolution required for two parties. - \item Resource. Depending of the type of data resource further work is required + \item Unidirectional/Bidirectional synchronization. For unidirectional + synchronization, no conflict resolution is required for two parties. + \item Resource. Depending of the type of data resource, further work is required to get changes. Is the resource able to tell which data changed since the last - synchronization, by its own? Or is further help/facility required to detect - which data changed since the last sync. Example: file systems, databases, - stacked data in a single file, ... + synchronization, on its own, or is further help/facility required to detect + which data changed since the last sync? For example: file systems, databases, + or stacked data in a single file. + % The following item is still quite awkward. \item Type of data. Is the data in a consistent format and supported by all - parties? File synchronization. Is the data not consistent and contains unique - information which doesn't allow to do a binary compare? Weak compare? Is + parties? File synchronization. Is the data inconsistent and does it contain unique + information which doesn't allow for a binary compare? Weak compare? Is conversion to a common format for different parties required? - \item Protocol. Does the protocol require to read only the latest changes or - all at once? - \item Transport. Are various transport layer involved? Does it require to - connect and disconnect in a specified way? Limited bandwidth? Example: - Bluetooth, USB, ... + \item Protocol. Does the protocol require reading only the latest changes or + all changes at once? + \item Transport. Are various transport layers involved? Does it need to + connect and disconnect in a specified way? Limited bandwidth? For example: + Bluetooth, or USB. \end{itemize} -You see, there lots of different circumstances which makes it quite complicated -to meet all the needs of different ways to synchronize and synchronization -protocols.\\ -This is also only the tip of the iceberg, since it describes only the -synchronization role of the ">Server"<. +There are many different circumstances, which makes meeting all the needs of different +ways to synchronize quite comlpicated.\\ +% You see, there are many different circumstances which make it quite complicated +% to meet all the needs of different ways to synchronize and synchronization +% protocols.\\ +This is only the tip of the iceberg, since it describes only the +synchronization role of the ``Server''. \section{Synchronization Role} -The term ">Server"< is quite confusing, +The term ``Server'' is quite confusing, especially in the combination of a synchronization protocol which uses a -transport protocol based on the ">Client"<- and ">Server<"-Model. Most famous -example is ">SyncML"<, which support among others the HTTP and OBEX protocol as -transport. You might know ">HTTP Server"< like the Apache Webserver and ">HTTP -Client"< like the Firefox Webbrowser. In SyncML you can have for example (same -for other transports supported by SyncML): +transport protocol based on the \emph{Client}- and \emph{Server}-Model. The most famous +example is \emph{SyncML}, which supports, among others, the HTTP and OBEX protocol for +transport. You might know \emph{HTTP Server} like the Apache Webserver and \emph{HTTP +Client} like the Firefox Webbrowser. In \emph{SyncML} you can have for example: \begin{itemize} \item HTTP Server transport and act as Synchronization Server \item HTTP Client transport and act as Synchronization Server \item HTTP Server transport and act as Synchronization Client \item HTTP Client transport and act as Synchronization Client \end{itemize} -OpenSync doesn't care much about Transport Server/Client role, this is -up to the Plugins. There is only a little detail which OpenSync have to care -about plugin when they're acting as the transport Server role, which is about +Likewise for other transport protocols supported be \emph{SyncML} + +% the second sentence is awkward +OpenSync doesn't care much about the Transport Server/Client role, this is +up to the Plugins. There is only a little detail that OpenSync has to care +about the plugin, when it is acting in the transport Server role, which is that the plugin has to be initialized all the time so the client can connect. More about this in the Plugin chapter.\\ \\ -Unfortunately OpenSync supports in version 0.40 only the Synchronization role -Server. The passive role as Synchronization Client isn't yet implemented, but is +Unfortunately, in version 0.40, OpenSync only supports the Synchronization Server +role. The passive role as Synchronization Client isn't yet implemented, but is on the top of the project agenda. The reason for this is that the current implementation of synchronization tasks/steps mentioned above are currently -fixed. As Synchronization Client the order and number of this synchronization -steps/tasks would differ to the Server role. More about this issue you can find +fixed. As a Synchronization Client, the order and number of this synchronization +steps/tasks would differ from the Server role. You can find more about this issue in the Framework Chapter in section Synchronization Role. \section{Slow Sync} -Various Synchronization protocols are using so called ">Slow Sync"< +Various Synchronization protocols are using the so called \emph{Slow Sync} synchronization technique. This consists of two types of synchronizations, the -already mentioned ">Slow Sync"< and a regular Synchronization (sometimes called -">Fast Sync<"). The difference between the Slow and the regular (Fast) Sync is +already mentioned \emph{Slow Sync} and a regular Synchronization (sometimes called +\emph{Fast Sync}). The difference between the Slow and the regular (Fast) Sync is that the regular one only transfers changes since the last synchronization. -This means on a regular synchronization not all entries have to be transfered, +This means, on a regular synchronization, not all entries have to be transfered, or converted. This makes the synchronization quite efficient and very fast. The -so called ">Slow Sync"< requests intentionally all entries, which makes the -synchronization a bit slower. Additionally the Synchronization Framework has to +so called \emph{Slow Sync} intentionally requests all entries, which makes the +synchronization a bit slower. Additionally, the Synchronization Framework has to interpret every single entry/change as newly added, since the Framework vanished -in advance the entire mappings and has to compare every single reported entry -from each party and find the fitting counterpart. This and the combination of -transferring all entries makes the synchronization compared to the regular -(Fast) synchronization very slow. The ">Slow Sync"< is only used in certain -cases to avoid data inconsistence and to keep all the data in sync. ">Slow -Sync"< got emitted in following circumstances: +in advance of the entire mappings and has to compare every single reported entry +from each party and find the fitting counterpart. This, and the transferring of +all entries, makes the synchronization much slower when compared with the regular +(Fast) synchronization. The \emph{Slow Sync} is only used in certain +cases to avoid data inconsistence and to keep all the data in sync. \emph{Slow +Sync} is emitted in following circumstances: \begin{itemize} \item First/Initial Synchronization -\item Party got reseted (same as first sync) -\item Party got synchronized in meanwhile within another environment +\item Party has been reset (same as first sync) +\item Party has been synchronized within another environment \item After an aborted/failed synchronization \end{itemize} + \section{Object Types} -The term ">Object Types"< is in OpenSync used to describe the type/category of -data. Example for ">Object Types"< are Contacts, Events, Todos, Notes or plain -Data (like the content of a file) and others. (It's not limited to PIM Data!). -Those Object Types get separated processed, to make it configurable which -Object Type should get synchronized. Example: Only synchronize contacts of the +The term \emph{Object Types} is used in OpenSync to describe the type/category of +data. Examples of \emph{Object Types} are Contacts, Events, Todos, Notes or plain +Data (like the content of a file). It's not limited to PIM Data! +Those Object Types processed separately, to make it configurable which +Object Type should get synchronized. For example: only synchronize contacts of the mobile, no events, todos nor notes. + \section{Formats} The ability to synchronize different Parties which use different formats, makes the OpenSync Framework to a very powerful Synchronization Framework. In OpenSync -each Format is associated with one Object Type (see previous chapter). This +each Format is associated with one Object Type (see previous chapter). Having this Object Type as common denominator for different formats makes it possible to determine a conversion path between different formats. The conversion path consists of various format converters, which are provided by Format Plugins. -Example: Two parties should synchronize their contacts (the Object Type). Party + +For example: two parties should synchronize their contacts (the Object Type). Party A stores the contacts as VCard 3.0 and Party B stores the contacts in some -Binary Format. To synchronize the VCard 3.0 and the Random Binary Contact Format +Binary Format. To synchronize the VCard 3.0 and the Random Binary Contact Format, format plugins have to register those formats and provide converters. The -Plugins don't have to provide converters for every known Format, often a certain +Plugins don't have to provide converters for every known Format; often a certain amount of converters to common formats or a common denominator format is enough to create a conversion path between VCard 3.0 to Binary Contact Format. + \section{Mappings} -If an entry got changed on one Party, the logical same entry has to be updated -on the other parties while synchronization. Often different parties use -different ids to identify their entries. So it's required to map the logical -same entries which each others native id. The combination of those different -entries on different parties are called ">Mappings"<. Those ">Mappings"< make it +If an entry has been changed on one Party, the logical same entry has to be updated +on the other parties during synchronization. Different parties often use +different ids to identify their entries. So it is necessary to map the logical +same entries to each others native id. + +The combination of those different +entries on different parties are called \emph{Mappings}. Those \emph{Mappings} make it possible to determine a conflict if mapped entries got changed on different parties the same time in a different way. + \section{Conflicts} -So called ">Conflicts"< appear if at least two entries of the same mapping got +So called \emph{Conflicts} appear if at least two entries of the same mapping got changed in a different way. No conflict appears if all entries of the mapping -changed the same way. Such conflicts have to be handled by the Synchronization +changed the same way. Conflicts have to be handled by the Synchronization Framework to avoid data loss. There are several ways to solve such conflicts. -OpenSync provides several different for a proper conflict resolution without -gaining unintended loss of data. Following conflict resolution are supported by +OpenSync provides several different methods for a proper conflict resolution without +unintended loss of data. The following conflict resolution methods are supported by the OpenSync Framework: \begin{itemize} \item Solve, means intentionally choosing one of the conflicting entries to -solve the conflict. The chosen one will be multiplied to all parties and will -overwrite the other conflicting changes. This also allows to configure in -advance who is the ">Winning"< Party, who's changes will always used as the -solving change (">master change"<) for the conflict. -\item Duplicate, (intentionally) will duplicate all changed entries. +solve the conflict. The chosen entry will be multiplied to all parties and will +overwrite the other conflicting changes. This also permits the user to configure in +advance who is the \emph{Winning} Party, who's changes will always used as the +solving change (\emph{master change}) for the conflict. +\item Duplicate, will (intentionally) duplicate all changed entries. \item Latest, using the latest changed entry of the conflicting entries. This is -only an conflict resolution option if all changes provide within their formats -enough information to determine which got most recently changed. -\item Ignoring, (temporarily) the conflict till the next synchronization. +only a conflict resolution option if all changes provide enough information within +their formats to determine which one was changed most recently. +\item Ignoring, (temporarily) the conflict until the next synchronization. Conflicting entries will be read and compared again by the OpenSync Framework on the next synchronization. To avoid inconsistence and data loss. If the entries/changes are equal on the next synchronization the conflict is solved as @@ -151,4 +163,4 @@ \section{Capabilities} \section{Filter} OpenSync provides initial code for filtering, but it's not yet usable within -OpenSync 0.40. Looking forward to OpenSync 0.41! +OpenSync 0.40. Look forward to OpenSync 0.41! ------------------------------------------------------------------------------ Stay on top of everything new and different, both inside and around Java (TM) technology - register by April 22, and save $200 on the JavaOne (SM) conference, June 2-5, 2009, San Francisco. 300 plus technical and hands-on sessions. Register today. Use priority code J9JMT32. http://p.sf.net/sfu/p _______________________________________________ Opensync-devel mailing list Opensync-devel@... https://lists.sourceforge.net/lists/listinfo/opensync-devel |
|
|
Re: Editing the Whitepaper
by Michael Bell
::
Rate this Message:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1 Hi John, John Ladan wrote: > > This is my first contribution. While reading the white paper, I noticed a bunch > of grammar errors (number, tense, syntax, etc.), so I decided to start fixing > them. A few stylistic changes worked their way in to make the language a > little more formal. I committed your patch as r5615. I have to excuse me because there is a typo in the commit message. Your front name is wrong (Johan). I'm really sorry about this. > Let me know how you like the changes. I can keep working on it if you want. > The patch for trunk is attached. The most of us are not English native speakers and yes, we really like these changes. So if you are willing to work on these things then you are more than welcome. Thanks a lot Michael - -- ___________________________________________________________________ Michael Bell Humboldt-Universitaet zu Berlin Tel.: +49 (0)30-2093 2482 ZE Computer- und Medienservice Fax: +49 (0)30-2093 2704 Unter den Linden 6 michael.bell@... D-10099 Berlin ___________________________________________________________________ PGP Fingerprint: 09E4 3D29 4156 2774 0F2C C643 D8BD 1918 2030 5AAB -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFJ6DnQ2L0ZGCAwWqsRAt9HAKCIL/p6AlnYhovwcrQxqGMoa/DhjACeMe/r X7ql6p5nRlpK8RadDdgSHPc= =cDjm -----END PGP SIGNATURE----- ------------------------------------------------------------------------------ Stay on top of everything new and different, both inside and around Java (TM) technology - register by April 22, and save $200 on the JavaOne (SM) conference, June 2-5, 2009, San Francisco. 300 plus technical and hands-on sessions. Register today. Use priority code J9JMT32. http://p.sf.net/sfu/p _______________________________________________ Opensync-devel mailing list Opensync-devel@... https://lists.sourceforge.net/lists/listinfo/opensync-devel |
| Free embeddable forum powered by Nabble | Forum Help |
