7 files changed, 129 insertions, 117 deletions

diff --git a/development/pim/pimpaper/backend.tex b/development/pim/pimpaper/backend.tex
index 2652b08..fcade7f 100644
--- a/development/pim/pimpaper/backend.tex
+++ b/development/pim/pimpaper/backend.tex
@@ -3,15 +3,15 @@
 \subsection{The Template}
-OPimAccessBackend is a template interface of the Backend. 
-It consists out of pure virtual functions to implement for
-load, reload, save and clear. You will also need to implement
-add, remove and replace.
-Todo, Event and Address inherit from OPimAccessBackend to create
-their Backend Type with additional functionality and also some
-default implementation for some queries.
+OPimAccessBackend is a template interface of the backend. 
+It consists out of pure virtual functions for
+load, reload, save and clear, add, remove and replace.
+Special inheritances from OPimAccessBackend for todo, calendar-event and conatact are available to 
+define the backend Type with additional functionality and some implementations for special queries.
 
-\subsection{Read Ahead}
-You may implement Read Ahead or Read Behind by implementing
-the specific find function. First you need to give the Frontend
+\subsection{Caching}
+You may implement caching by implementing a specific find function. It is filling the cache 
+(located in the frontend) as read-ahed or read-behing, by giving a read direction. 
+\comment{ Das versteht an dieser Stelle keiner: First you need to give the Frontend
 a hint on how many items you want to cache and then you can call
 cache to cache items.
-read Ahead returns the number of Records to read behind/ahead.
+read-ahead returns the number of records to read behind/ahead.}
+Caching is used automatically, if this function is implemented.
diff --git a/development/pim/pimpaper/backendimplementation.tex b/development/pim/pimpaper/backendimplementation.tex
index 272507a..a222be8 100644
--- a/development/pim/pimpaper/backendimplementation.tex
+++ b/development/pim/pimpaper/backendimplementation.tex
@@ -1,4 +1,4 @@
 \section{Implementation of the Backends}
-Opie Backends have implementations for XML, VCF and SQL. We can
-group the VCF and XML Backend in the File Family.
+Opie provides backend implementations for XML, VCF and SQL. XML and VCF are file based
+implementations, while the SQL backend use a real database.
 
@@ -6,18 +6,20 @@ group the VCF and XML Backend in the File Family.
 Opie PIM encourages that all changes are made visible 
-immediately and are propagated by Qt Signals by the Frontend
-but we recognize that not every Backend
-- specially the File Family - is capable of making every 
-change physically available instantly or it would be too
-complex to develop this is why this feature is nice to have
-but not necessary implement by the Backend.\\
-By default changes may not be lost by concurrent access and two different
-saves. The feature to implement is called Auto-Update the Backends
-can utilize QCOP for the communication. When one Backend saves the data
-it needs to lock the access (it can use API), check if external changes
-occurred and reload the data if necessary and then save the merged changes
-and finally to give up the lock.
-The user may call reload() any time and the access needs to be locked
-for that. The Backends can use the appropriate techniques to provide
-fast and secure operation.\\
-The reload feature may be turned off for the Frontend so that a save()
+immediately and are propagated via Qt Signals by the frontend.
+Due to performance issues, we recognize that not every backend
+implementation - especially the file based - is capable of making every 
+change physically available instantly, called ``Live Update''. It would be too complex to 
+implement this efficiently, thus we declare this as ``nice to have'' feature, 
+which may be implemented by the backend.\\
+By default changes should not be lost by concurrent access to the files. 
+The requested feature to avaoid this, is called ``Auto-Update''.  
+If one backend need to save the data, it has to lock the access (it can use API \comment{Was?}), check whether external changes
+occurred since last save and reload and merge the data, if necessary. This merging guarantees to include all external changes 
+to the local dataset. Afterwards it saves all data and removes the lock.
+\comment{ Was willst Du hier genau sagen? The user may call reload() at any time and the access needs to be locked
+for that.} The backends has to use the appropriate technique to provide
+fast and secure operations.\\
+\comment{Ich würde im Folgenden eher das vorschlagen:
+The reload feature may be turned off by the frontend to disable automatic update. In this case, the
+backend should work in ``read-only'' mode to prevent possible overwrite of changes}
+The reload feature may be turned off by the frontend so that a save()
 might possible override changes that occurred.
@@ -25,10 +27,11 @@ might possible override changes that occurred.
 \subsubsection{Journal and Out Of Memory}
-The Backend need to make sure that it is capable of surviving crashes
+The backend need to make sure that it is capable of surviving crashes
 and storage out of memory situation without losing data and changes.\\
-The File Family is encouraged to use the journal on a per user basis 
+The file based backends is encouraged to use a journal-file on a per user basis 
 to keep track of changes. The journal can be applied in case of a crash.\\
-In out of disk storage situation the user needs to be informed so it might
-free space.
+In out of disk storage situation the user needs to be informed, so he should get the chance to
+free space before the operation is stopped.
+Database based backends should use mechanisms which are provided or suggested for the database system, used.
 
-\subsubsection{Features of the Backends}
+\subsubsection{Features of the backends}
 
@@ -37,3 +40,3 @@ free space.
 \hline
-Backend & Live Update & Auto Update & Journal  & Available\\ \hline
+backend & Live Update & Auto Update & Journal  & Available\\ \hline
 XML & no  & yes & no but SQL & after save \\ \hline
@@ -42,3 +45,3 @@ VCF & no  & no  & no         & never      \\ \hline
 \end{tabular}
-\label{Feature of Backends}
+\label{Feature of backends}
 \end{center}
diff --git a/development/pim/pimpaper/frontend.tex b/development/pim/pimpaper/frontend.tex
index 1ed41aa..9c46c07 100644
--- a/development/pim/pimpaper/frontend.tex
+++ b/development/pim/pimpaper/frontend.tex
@@ -3,8 +3,7 @@
 \subsection{Low Level Frontend}
-OPimBase is a low level not value based interface, to do basic queries
-and record finding in a generic way. It is present to allow
-generic access to all Frontends.
+For general (typeless) operations, OPimBase provides a real low level, reference based, interface, for basic queries
+and record finding. These operations are common to all frontends.
 
 \subsection{OTemplateBase}
-Inherits from OPimBase and implements bits of the OPimBase Interface.
+Inherited from OPimBase and implements bits \comment{bits? Teile ? Welche Teile ? Sollte es nicht eher vervollständigen heissen?} of the OPimBase Interface.
 This class is present to be used by the Backends ( OPimAccessBackend )
@@ -15,10 +14,11 @@ Implements OTemplateBase and OPimBase. All low level functions are
 automatically implemented by the OPimAccessTemplate which does
-additional type checking based on OPimRecord::rtti.\\
-This template is value based and utilizes the Backend. The Backend
-can be set on the Constructor, when no Backend is specified
-the default Backend Implementation will be used.
-This AccessTemplate operates on OPimRecord based types and is meant
-to be used by concrete Frontend implementations for Todo, Event,
-Note and Address. The concrete Frontends can be used by applications.
-Use this template to create your own PIM Type.
+additional type checking, based on OPimRecord::rtti.\\
+This template is value based and utilizes the backend. The backend
+can be set on instancing by the constructor. If no backend is specified,
+the default implementation will be used (which one is defined by the config file
+pimaccess.conf).
+This AccessTemplate operates on types, based on OPimRecord and is meant
+to be used by concrete frontend implementations for todo, datebook-event,
+note and contact. The concrete frontends can be used by applications.
+Use this template to create new PIM types.
 
diff --git a/development/pim/pimpaper/gui_xref.tex b/development/pim/pimpaper/gui_xref.tex
index d869c5f..f86e618 100644
--- a/development/pim/pimpaper/gui_xref.tex
+++ b/development/pim/pimpaper/gui_xref.tex
@@ -1,5 +1,7 @@
 \section{GUI Classes}
+GUI elements should be provided for modifying records in a general way. The next sections 
+shows suggested widgets for this purpose.
 
 \subsubsection{Recurrence Widget}
-Opie PIM offers a recurrence Widget to let the user
+Opie PIM offers a recurrence widget to let the user
 configure the recurrence.
@@ -7,3 +9,3 @@ configure the recurrence.
 \subsubsection{Mainwindow}
-The mainwindow implements a QCOP Interface for showing, 
+The mainwindow implements a QCOP interface for showing and 
 editing records. It can handle alarms and reminder activation.
@@ -13,8 +15,7 @@ editing records. It can handle alarms and reminder activation.
 \subsection{The idea}
-Sometimes an Event or Todo is related to something else. 
-For example the Birthday Attribute of your children Record relate
-to the Birthday Event in your Datebook and the ``Book clown''
-in your Todolist.\\
-We need a way to select the Record and the attribute if we want
-that fine grained information.
+Sometimes a datebook-event or todo is related to something else. 
+For example, the birthday attribute of a child record relate
+to the birthday event in a datebook and to the entry ``Book clown''
+in your todolist.\\
+We need a way to interconnect information to describe such relations.
 
@@ -22,19 +23,22 @@ that fine grained information.
 \subsubsection{Out Of Process Selection}
-For an Out of Process solution we could utilize the targeted
-Application to request the selection of an record.\\
+For an out of process solution, we could utilize the targeted
+application to request the selection of an record.\\
 For that to work we need to know which application offers
-Cross Referencing and the API needs to be able to find the
+cross referencing. The API needs to be able to find the
 application and then call them via QCOP.\\
-Later for resolving the Cross Reference the same application\\
+Later, for resolving the cross-references, the same application\\
 would be either asked to give a summary string or it could
 display the reference on demand. This requires the application
-to start and a specific selection window, but more easily
-allows to cross reference attributes.
+to start a specific selection window, but more easily
+allows to cross reference attributes. \comment{``, but..'' Das verstehe ich nicht!. Ich wuerde den Satz so uebersetzen:
+Dies erfordert, dass die Application ein spezielles Auswahlfenster startet, aber viel einfacher die
+Crossreferenzierung von Attributen erlaubt.
+Meinst Du das ? }
 
-\subsubsection{In Process Selection}
-In Process Selection is possible with the usage of OPimBase 
+\subsubsection{In-Process-Selection}
+In-process-selection is possible using OPimBase 
 and OPimRecord. It allows to query and sort in a generic way.
-This would allow to have a generic Selector widget which
-can be used to select a Record and possible files as well. To
-support new types one could dlopen the Frontends to allow
-custom Frontends.
+This would allow to have a generic selector widget, which
+can be used to select a record and possible files as well. To
+support new types it should be possible to use plugins (via dlopen) do load
+and support custom frontends.
diff --git a/development/pim/pimpaper/introduction.tex b/development/pim/pimpaper/introduction.tex
index 24cf586..5241d5e 100644
--- a/development/pim/pimpaper/introduction.tex
+++ b/development/pim/pimpaper/introduction.tex
@@ -7,3 +7,3 @@ It will examine the separation between Frontend and Backend, delayed
 loading of Records, the concrete XML, SQL and VCF implementation
-of the Backend and finally we will built a new Frontend/Backend
+of the Backend and finally, we will built a new Frontend/Backend
 to support a Note based API.
diff --git a/development/pim/pimpaper/opiepim.tex b/development/pim/pimpaper/opiepim.tex
index 0b26083..89e6292 100644
--- a/development/pim/pimpaper/opiepim.tex
+++ b/development/pim/pimpaper/opiepim.tex
@@ -7,2 +7,4 @@
 
+\newcommand{\comment}[1]{}
+
 \begin{document}
@@ -31,4 +33,8 @@
 \begin{tabular}[t]{|c|c|c|} \hline
-\textbf{Version} & \textbf{Author} & \textbf{Email} \\ \hline\hline
-0.0.1 & Holger Freyther & zecke@handhelds.org \\ \hline
+\textbf{Version} & \textbf{Author} & \textbf{Email} \\ 
+\hline\hline
+0.0.1 & Holger Freyther & zecke@handhelds.org \\ 
+\hline
+0.0.2 & Stefan Eilers & eilers.stefan@epost.de \\
+\hline
 \end{tabular}
diff --git a/development/pim/pimpaper/seperation.tex b/development/pim/pimpaper/seperation.tex
index 544d5c1..e865fb0 100644
--- a/development/pim/pimpaper/seperation.tex
+++ b/development/pim/pimpaper/seperation.tex
@@ -3,8 +3,9 @@
 \subsection{The Record}
-With our API everything is based on a  OPimRecord, this record
-got a Identifier which is unique to the Backend it belongs, it is
-also possible to assign a new Unique Identifier (uid) on a newly
+The basic component of our API is the OPimRecord. Every record is identified
+by an identifier, which is unique to the backend it belongs to 
+\comment{Why it is just unique to the backend? (eilers)}. 
+If expected, is also possible to assign a new Unique Identifier (UID) on a newly
 created OPimRecord.\\
-The OPimRecord allows to assign Categories this record is in, to get
-a Rich Text summary of the content of the Record and finally to match 
+The OPimRecord allows to be assigned to categories, to provide a Rich Text 
+summary of its content and finally to match 
 the content of the Record with a regular expression.
@@ -12,19 +13,19 @@ the content of the Record with a regular expression.
 \subsection{The Frontend}
-Opie PIM got Frontends to access Todos, Events and Addressees. Using
-the default Constructor of either OTodoAccess, ODatebookAccess or
-OContactAccess uses the default data. These Access methods offer
-the common load, save, clear, reload methods and have all in common
-to query for an example record, sort a list of records for specific
-characteristics, and to match the content against a regular expression
- and give access to the Records inside the database/storage.\\
-The Frontend provide a value based Interface and operates on Records
-that inherit from OPimRecord and add extra task specific methods to it.
+Opie PIM implements frontends to access Todos, Datebook-Events and Addresses.
+The frontend provides a value based interface and operates on records inherited 
+from OPimRecord and add extra task specific methods to it.
+
+Access methods offer the common load, save, clear, reload methods, 
+give access to the records inside the database/storage and implement a general
+interface to query, for example, a record, request a sorted lists of records for specific
+characteristics and to match the content against a regular expression.\\
 
 \subsection{ORecordList and Iterator}
-The result of a query or the content of the database is a ORecordList.
-To iterate over a ORecordList you can use the Iterator. The Iterators
-behaves like the Iterators found in Qt and on dereferencing you get
-the reference to the record. Internally the record is fetched just
-in time. This delayed loading allows to exploit full power of the specific
-Backend.
+The result of a query or the content of the database is is abstracted by an ORecordList.
+To iterate over an ORecordList useing an Iterator. 
+Using STL like iterators, it is possible to iterate through an ORecordList.
+Accessing a record is easy possible by dereferencing the iterator.
+Internally, the record is fetched just in time, called delayed loading. 
+This delayed loading allows to exploit \comment{exploit??} full power of the specific
+backend.
 
@@ -32,34 +33,32 @@ Backend.
 \subsection{The Backend}
-The Backend is a template based interface that operates on OPimRecord
-inherited data types. To implement the delayed loading the Backends
-Implementation return only a list of UIDs and these get converted
-to a OPimRecordList<T> by the Frontend.
+The backend is a template based interface that operates on data types, inherited from OPimRecord.
+Delayed loading is implemented by the idea of storing just a list of UIDs instead complete records 
+in an OPimRecordList<T> by the frontend and to fetch the records just on demand.
 
-\subsection{The cache and read ahead}
-To speed up the repeated lookup of records, specially when iterating
-over the OPimRecordList we've a cache in the Frontend which is filled
-by the Backend and specially in the iterator case the Backend
-can do a read ahead to fill the cache.
+\subsection{Caching}
+To speed up the repeated lookup of records, especially while iterating
+over the OPimRecordList, a caching mechanism, located in the frontend, is filled
+by the backend automatically.
 
 \subsection{Backend vs. Frontend}
-The Frontend is meant to be used by the normal API user to access
-and query the Records and to save it with  different Backend to
-a different file if needed.
-The Backend is used to implement concrete storage such as XML, VCF
-and SQL and exploit possible features of the chosen storage. For example
-a SQL  Backend can use the power of query, lookup, sorting of the database
+The frontend is meant to be used by the user API to access
+and query the Records. \comment{ Ist hier irrelevant und verwirrt: and to save it with  different backend to
+a different file if needed}.
+The backend is used to implement the real storage, such as XML, VCF
+and SQL and exploit \comment{exploit?} special features of the chosen storage. For example
+a SQL  backend can use the power of query, lookup, sorting of the database
 and do true delayed loading of records whereas the XML resource on
-a simple file-system normally can't (XMLLiveConnect on ReiserFS). On remote
-Backends such as LDAP one might want to use delayed initialisation and
-fetching of records as well. Due the clean separation of Frontend and Backend
-this is possible but the ease of development and deployment 
-of both Backends and Frontend remain.
+a simple file-system normally can't (XMLLiveConnect on ReiserFS\comment{???}). 
+On remote backends, such as LDAP, one might want to use delayed initialisation and
+fetching of records as well. Due to the clean separation of frontend and backend,
+it is possible to use the power of the used databases, but still keep the ease of development 
+and deployment.
 
 \subsection{Occurrences}
-A Frontend/Backend can be queried to include OPimRecords for a 
-period of time. Traditionally this only applies to Events but 
-with the Opie1.2 revision of PIM this can also be applied to
-Todo, Address and Notes.
-It behaves similar to OPimRecordList and supports the delayed
-loading of Records.
+A frontend/backend can be queried to provide OPimRecords which occur in a 
+period of time. Traditionally this only applies to Calendar-Events, but 
+due to the the revision of Opie (release 1.2), this can also be applied to
+Todo, Address and Notes, as well.
+OPimOccurence behaves similar to OPimRecordList and supports the delayed
+loading of Records as described above.