QOF - Query Object Framework
                ----------------------------

Packagers and maintainers: Please see the HACKING file
for specific advice on building against and packaging QOF.
(HACKING is a text version of the 'hacking.html' page
from the QOF website or QOF documentation.)

Please see the NEWS file and the ChangeLog for detailed
information on changes since 0.6.0.

0.7.0 release
-------------

The date and time handlers have been overhauled and
there are large changes. Timespec has been deprecated 
and replaced by QofTime which is an opaque type. QofTime 
has completely replaced the previous code and includes 
handlers to avoid pitfalls of incompatible date/time format 
conversions. QofTime only handles times in seconds.
All date handling is done exclusively in a new type, QofDate,
an extended version of struct tm. Applications using QOF
should now use QofTime to replace time_t and QofDate to
replace struct tm. Functions like localtime, gmtime, mktime
and time can be used externally - subject to the more limited
range of values supported in each case.

QOF_TYPE_DATE is now deprecated, to be replaced by
QOF_TYPE_TIME. This is the first change in the QofObject
API in libqof1 and requires significant changes within
all QOF objects to be supported by libqof2. libqof2 will
therefore use a incremented QOF_OBJECT_VERSION. libqof1
retains the existing version, using QOF_TYPE_TIME as an
optional extra. Packages using QOF_TYPE_TIME need to depend
on QOF >= 0.7.0

QofTime is opaque, firstly, to implement strict validity
checking and secondly to ensure consistent handling
within objects. QofTime and QofDate now support all
times and dates within a couple of dozen times the age of
the universe by using 64bit values wherever necessary.

The Doxygen documentation is now built automatically -
depending on your distribution, a libqof-doc package
should be available to install that will provide the
HTML at: /usr/share/doc/libqof-doc/html/index.html

0.7.0 introduces strftime and strptime extended code
based on the Debian coreutils package (specifically the 'date'
command) and the glibc source code, providing support for 
nanosecond formats and the full range of QofTime and QofDate.

0.6.0 final release - October 2005.
-----------------------------------

The logging subsystem has been overhauled to make it more
generic and easier to use with other applications.

The backends are now loaded using GModule which requires each
backend to use QofBackendProvider and install the .la file
alongside the backend library in the *main* package, not the
-dev or -devel package.

v0.6.0 introduces libqof1 which will remain API compatible
until all the changes below can be folded into libqof2:

	1. All gnucash-specific code to be removed. Most of this
		has been done in v0.6.0
	2. Filename and function name conventions to be made to 
		conform to a single method:
		filenames: qof<module>.c|h
		functions: qof_<module>_<function>_ ...
		e.g. gnc_date.h becomes qofdate.h
		qof_book_mergeInit becomes qof_book_merge_init
		gnc_numeric_zero becomes qof_numeric_zero
		gnc_set_logfile becomes qof_log_setfile.
		gnc-trace.c|h becomes qoflog.c|h
	3. These changes will be made by deprecating old names
		and making old files into placeholders. When libqof2
		is ready for pre-release, all deprecated elements will
		include compiler flags that will highlight the code that
		needs to be changed and placeholder files may be removed
		at this stage. All flags and deprecated code will
		then be removed in the final libqof2 release.
	4. To make this change easier, the qof.h header has been fixed
		in v0.6.0 and is now the only header file required to be
		included to use QOF. Using individual header files in 
		applications linked against QOF is now *deprecated*. All
		code that uses QOF should only use:
		#include <qof.h>
		// or
		#include "qof.h"
		This is the only file guaranteed to maintain access to the
		full QOF API during the entire life of libqof1 and libqof2.
		

0.6.0-pre1 release notes - Sept 05
----------------------------------

QOF v0.6.0 adds a lot of new code, including a new backend, book
merge support, new data types and improved methods for loading
other suitable backends. This pre-release is a test-bed and some
functions may require further work.

New this release:
-----------------
 o QofBook merge support with collision handling.
 o Support for partial books with references to linked objects.
 o XML backend available to all programs using QOF. A generic format
   to describe any object in XML.
 o Methods to convert objects between applications.

Brief Description:
------------------
QOF - Query Object Framework is a library for adding a query engine 
to C applications.  An SQL database is not needed; any collection
of C/C++ objects can act as 'tables' which can be 'joined' using 
an SQL-like programming interface.

Long Description:
-----------------
QOF is an offshoot of the GnuCash engine, consisting of those pieces 
unrelated to accounting.  The Query Engine allows C/C++ applications 
to treat random collections of objects as if they were SQL tables,
and perform table-join type queries across them.  In addition, the 
query engine can be backed by an actual database, so that instances
of local objects can act as a 'cache' to a much larger SQL database.

QOF also includes other utilities from GnuCash:
 o Key-Value Pair trees (KVP aka slots and frames), for providing 
   extensibility by associating arbitrary-format data with an object, 
   using a URL-like identifier.
 o Universally-unique 128-bit ID support, so that an instance of an 
   object can be obtained from its unique identifier, thus simplifying
   associations, cross-network operation, etc.
 o Rational Number Support, providing exact math for working with
   money or prices or other quantities.
 o Miscellaneous date & time utilities.
 o Program tracing infrastructure; handing for tracing/debugging
   complex applications.
 o QofBook merge support with collision handling.
 o Support for partial books with references to linked objects.
 o XML backend available to all programs using QOF. A generic format
   to describe any object in XML.
 o Methods to convert objects between applications.

The system consists of 15 KLOC of C code that has been ported to many
Unixes, including Mac OS X.  Although this code is in production use
in stable versions of GnuCash, the split-off into QOF is recent and
still under some flux in order to flesh it out.  In particular, the
subroutine naming convention is being resolved but is still inconsistent.

Examples:
--------
Example programs showing usage can be found in the "examples" subdirectory
but are becoming obsolete. Instead, generate your own objects:

Generating objects:
------------------
To generate your own QOF objects, including Makefiles and an outline
test application, see http://qof-gen.sourceforge.net/

Other applications:
-------------------
Pilot-QOF implements a QOF application conduit for pilot-link,
supporting Expenses, ToDo, Calendar and Contacts databases. Support
can be extended to FreeCoins and other Palm databases in time.

Documentation:
--------------
The QOF documentation is entirely embedded in the source code. You
can build an html version of the documentation by installing the
'doxygen' package, and then 'cd doc; make doc'.  Skim the doc/README
file for more info.

Linking/Building
----------------
This version of QOF uses the 'pkg' system of managing include files
and libraries.  To compile and link your program against QOF, see the
example in the HACKING file.

------------------------- END OF DOCUMENT -------------------------