pilot-qof -- Querying Palm databases as objects

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

The code and other related files in this distribution are licensed under the
GNU General Public License or "GPL". 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.

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

This code is under active development. If you would like to contribute to
the project, you can contact the developer(s) 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).

------------
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

