pilot-qof --   Querying Palm databases as objects
datafreedom -- convert PIM data between applications

----------------
Licence
----------------

The code and other related files in this distribution are licensed under the
GNU General Public License or "GPLv3". This licence is included in the file
COPYING. XSL stylesheets from EXSLT are public domain. XSL stylesheets from
XSLTSL are licensed under the GNU Lesser General Public Licence, LGPL v2.1.

----------------
About Pilot-QOF
----------------

If you would like to contribute to the project, you can contact the developer 
using the QOF-devel mailing list. Subscribe at 
http://lists.sourceforge.net/lists/listinfo/qof-devel

Homepage: http://pilot-qof.sourceforge.net/

Pilot-QOF converts Palm databases to queriable objects. A Palm database record
is an instance of the object, called an Entity. Objects are collated to form
one data source, called books, that can contain any number of different objects -
depending on the application running QOF. Pilot-QOF writes selected palm data to
QSF XML offline storage and running SQL-type queries on the live data or XML file.
Pilot-QOF currently supports the four main applications (Expenses, Contacts,
Calendar and ToDo).

------------------
About Data Freedom
------------------

Data Freedom is about being able to liberate your data from one application and 
make it seamlessly available on another. Data Freedom also seeks to help liberate 
your data from one platform and make it seamlessly available on another. Rather 
than reverse engineering specific troublesome file formats, data-freedom 
concentrates on encouraging the development of implementation architectures and 
conceptual foundations to synchronise arbitrary data.The goal is to encourage 
generic data handling using extensible mechanisms that are inter-related to allow 
free exchange of data between disparate applications, systems, architectures and 
platforms.Each implementation is free to choose the most suitable method of 
providing data and receiving data. All that is required is that the method chosen 
is as open, extensible and generic as possible. Naturally, the eXtensible Markup 
Language - XML - features strongly, as does perl. For more information on data 
freedom: 

Homepage: http://www.data-freedom.org/

As of v0.1.3, pilot-qof supports being split into multiple packages, allowing the
main pilot-qof binary to be isolated from the documentation, XSL stylesheets and
perl scripts. In future, the datafreedom contents may be split out from pilot-qof
CVS.

------------
PURPOSE
------------

Pilot-QOF  is intended for use with pipes as well as ordinary files and
so Pilot-QOF will always try to output only valid XML.  Error  messages
will  be output but if no errors are found, pilot-qof remains silent. A
message "Your query matched no objects" would break this model because,
in real usage, an empty XML book can actually be a usable result.

------------
Timezones
------------

Pilot-link itself does not directly support users who cross timezones with
their Palm - users are reminded that if timezone issues are important to their
DateBook or Expenses data, it would be wise to change the Palm Preferences to use
the same timezone as the computer running pilot-qof. Once in QOF, all dates and
times are UTC so the QSF XML files can be freely exchanged across timezones without
complication.

------------
TRANSLATIONS
------------

Palm Appointments use the name of the weekday to indicate certain
repeat  events. This value is local to the timezone of the Palm and
pilot-qof will translate the value to match. If you need to transfer
such events to a user with a different locale, configure the host PC to
the same locale as the end user. pilot-qof will then translate the
weekday name and write it into the XML. Remember to also set the Palm
to the locale of the end user so that the timezone information is  pre-
served in UTC, as above.

----------------------
REPEATING APPOINTMENTS
----------------------

When an appointment repeats, the Palm stores the start date, the repeat
frequency and end date as well as a series of exceptions that normally
occur when the user deletes the current appointment from a repeating
series. This system is compact but not easy to query for specific dates
in the chain. So pilot-qof creates temporary appointments for each of
the repeats, skipping the exceptions. This makes it  easy to find  an
event on a specific date,  whether or not it was a repeating event.
These extra appointments are written out to the QSF XML so that 
processes that  parse and/or query the XML data do not have to understand
the Palm repeat system. When datebook data is  uploaded to the Palm,
pilot-qof ignores all these extra appointments and reinstates the Palm
record. If appointments are modified in the XML, pilot-qof will attempt
to mark any gaps as additional exceptions in the Palm.


------------
Bugs
------------

Please report any bugs via the SourceForge project site:
https://sourceforge.net/projects/pilot-qof/
or the QOF-devel mailing list:
http://lists.sourceforge.net/lists/listinfo/qof-devel

